refactor(blueprint): select the component resolver by the form of the reference

README.md

@@ -36,7 +36,10 @@ Or bind by glob in VS Code `settings.json`:
 ```json
 {
   "yaml.schemas": {
-    "https://schemas.musher.dev/component/v1/component.schema.json": "**/components/*.yaml",
+    "https://schemas.musher.dev/component/v1/component.schema.json": [
+      "**/components/*.yaml",
+      "**/component-*.yaml"
+    ],
     "https://schemas.musher.dev/blueprint/v1/blueprint.schema.json": "**/blueprint.yaml",
     "https://schemas.musher.dev/listing/v1/listing.schema.json": "**/listing.yaml"
   }

catalog.json

@@ -17,7 +17,11 @@
       "description": "Musher component document — one reusable workload definition.",
       "fileMatch": [
         "**/components/*.yaml",
-        "**/components/*.yml"
+        "**/components/*.yml",
+        "**/component.yaml",
+        "**/component.yml",
+        "**/component-*.yaml",
+        "**/component-*.yml"
       ],
       "name": "Musher Component Document",
       "url": "https://schemas.musher.dev/component/v1/component.schema.json",

conformance/blueprint/v1/cases.json

@@ -31,6 +31,36 @@
       "id": "structural-005-nested-unknown-field",
       "phase": "structural",
       "path": "structural/005-nested-unknown-field"
+    },
+    {
+      "id": "structural-006-local-component-reference",
+      "phase": "structural",
+      "path": "structural/006-local-component-reference"
+    },
+    {
+      "id": "structural-007-published-component-reference",
+      "phase": "structural",
+      "path": "structural/007-published-component-reference"
+    },
+    {
+      "id": "structural-008-bare-component-stem",
+      "phase": "structural",
+      "path": "structural/008-bare-component-stem"
+    },
+    {
+      "id": "structural-009-version-pinned-on-local-reference",
+      "phase": "structural",
+      "path": "structural/009-version-pinned-on-local-reference"
+    },
+    {
+      "id": "structural-010-published-reference-without-version",
+      "phase": "structural",
+      "path": "structural/010-published-reference-without-version"
+    },
+    {
+      "id": "structural-011-traversal-inside-local-reference",
+      "phase": "structural",
+      "path": "structural/011-traversal-inside-local-reference"
     }
   ]
 }

conformance/blueprint/v1/structural/001-minimal-valid/case.yaml

@@ -6,7 +6,7 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
   parameters: {}

conformance/blueprint/v1/structural/002-wrong-kind/case.yaml

@@ -8,7 +8,7 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
   parameters: {}

conformance/blueprint/v1/structural/003-unknown-field/case.yaml

@@ -8,7 +8,7 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
   parameters: {}

conformance/blueprint/v1/structural/004-unsupported-spec-version/case.yaml

@@ -8,7 +8,7 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
   parameters: {}

conformance/blueprint/v1/structural/005-nested-unknown-field/case.yaml

@@ -9,7 +9,7 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
   parameters:

conformance/blueprint/v1/structural/006-local-component-reference/case.yaml

@@ -0,0 +1,21 @@
+# The repo-local reference form, in both layouts it has to support: a nested
+# `components/` directory and a flat sibling file. The `./` prefix is what
+# selects the local resolver — without it a bare slug and a UUID are
+# indistinguishable, since a UUID beginning with a hex letter satisfies the
+# slug grammar.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: web-and-database
+  version: 1
+spec:
+  components:
+    db:
+      component: ./components/postgres.yaml
+      size: general.standard.small
+      connections: {}
+    web:
+      component: ./component-web.yaml
+      size: general.standard.small
+      connections: {}
+  parameters: {}

conformance/blueprint/v1/structural/006-local-component-reference/metadata.json

@@ -0,0 +1,7 @@
+{
+  "id": "structural-006-local-component-reference",
+  "phase": "structural",
+  "expected": "pass",
+  "clause": "specifications/blueprint/v1/spec.md#component-reference",
+  "summary": "A repo-local component reference validates from any directory layout, nested or flat."
+}

conformance/blueprint/v1/structural/007-published-component-reference/case.yaml

@@ -0,0 +1,16 @@
+# The published reference form: a component UUID plus the lineage version it
+# pins. The version is required here because, unlike a local reference, there
+# is no document on disk whose `metadata.version` could supply it.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  components:
+    db:
+      component: 550e8400-e29b-41d4-a716-446655440000
+      componentVersion: 3
+      size: general.standard.small
+      connections: {}
+  parameters: {}

conformance/blueprint/v1/structural/007-published-component-reference/metadata.json

@@ -0,0 +1,7 @@
+{
+  "id": "structural-007-published-component-reference",
+  "phase": "structural",
+  "expected": "pass",
+  "clause": "specifications/blueprint/v1/spec.md#component-reference",
+  "summary": "A published component reference is a UUID carrying the lineage version it pins."
+}

conformance/blueprint/v1/structural/008-bare-component-stem/case.yaml

@@ -0,0 +1,16 @@
+# A bare file stem, the form this family used before the reference was
+# discriminated by shape. It is rejected because it is ambiguous: the slug
+# grammar `^[a-z][a-z0-9-]{0,61}[a-z0-9]$` also matches a UUID that begins
+# with a hex letter, so a reader cannot tell a stem from a published id.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  components:
+    db:
+      component: postgres
+      size: general.standard.small
+      connections: {}
+  parameters: {}

conformance/blueprint/v1/structural/008-bare-component-stem/diagnostics.json

@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_INVALID_VALUE",
+    "path": "/spec/components/db/component"
+  }
+]

conformance/blueprint/v1/structural/008-bare-component-stem/metadata.json

@@ -0,0 +1,7 @@
+{
+  "id": "structural-008-bare-component-stem",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/blueprint/v1/spec.md#component-reference",
+  "summary": "A reference carrying neither a relative-path prefix nor a UUID matches no resolver and is rejected."
+}

conformance/blueprint/v1/structural/009-version-pinned-on-local-reference/case.yaml

@@ -0,0 +1,16 @@
+# A local reference that also pins a version. The referenced document already
+# carries its own `metadata.version`, so a second version here could disagree
+# with it and there would be no rule saying which one wins.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  components:
+    db:
+      component: ./components/postgres.yaml
+      componentVersion: 3
+      size: general.standard.small
+      connections: {}
+  parameters: {}

conformance/blueprint/v1/structural/009-version-pinned-on-local-reference/diagnostics.json

@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_INVALID_VALUE",
+    "path": "/spec/components/db/componentVersion"
+  }
+]

conformance/blueprint/v1/structural/009-version-pinned-on-local-reference/metadata.json

@@ -0,0 +1,7 @@
+{
+  "id": "structural-009-version-pinned-on-local-reference",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/blueprint/v1/spec.md#component-reference",
+  "summary": "componentVersion on a local reference is rejected; the version is the referenced document's own."
+}

conformance/blueprint/v1/structural/010-published-reference-without-version/case.yaml

@@ -0,0 +1,15 @@
+# A published reference with no version. Nothing on disk carries the lineage
+# version for this form, so omitting it would leave the node pinned to
+# whatever the registry serves at deploy time.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  components:
+    db:
+      component: 550e8400-e29b-41d4-a716-446655440000
+      size: general.standard.small
+      connections: {}
+  parameters: {}

conformance/blueprint/v1/structural/010-published-reference-without-version/diagnostics.json

@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_MISSING_FIELD",
+    "path": "/spec/components/db"
+  }
+]

conformance/blueprint/v1/structural/010-published-reference-without-version/metadata.json

@@ -0,0 +1,7 @@
+{
+  "id": "structural-010-published-reference-without-version",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/blueprint/v1/spec.md#component-reference",
+  "summary": "A published reference without componentVersion is rejected rather than floating on the registry."
+}

conformance/blueprint/v1/structural/011-traversal-inside-local-reference/case.yaml

@@ -0,0 +1,17 @@
+# A local reference spelling a traversal into an interior segment. Every
+# segment must begin with a letter or digit, so `..` cannot appear except in
+# the leading prefix. Two spellings of one target would otherwise both be
+# valid, and the semantic containment check would have to normalise before it
+# could compare.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  components:
+    db:
+      component: ./components/../../etc/passwd.yaml
+      size: general.standard.small
+      connections: {}
+  parameters: {}

conformance/blueprint/v1/structural/011-traversal-inside-local-reference/diagnostics.json

@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_INVALID_VALUE",
+    "path": "/spec/components/db/component"
+  }
+]

conformance/blueprint/v1/structural/011-traversal-inside-local-reference/metadata.json

@@ -0,0 +1,7 @@
+{
+  "id": "structural-011-traversal-inside-local-reference",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/blueprint/v1/spec.md#component-reference",
+  "summary": "A local reference with a traversal in an interior segment is rejected before containment is considered."
+}

specifications/blueprint/v1/examples/minimal.yaml

@@ -2,6 +2,11 @@
 #
 # A single-component blueprint. Parameters are empty, so they are derived from
 # the merged USER-supplied inputs of the referenced components.
+#
+# `component` is a repo-local reference: it resolves relative to the directory
+# holding this file, and the version it deploys is that document's own
+# `metadata.version`. The paths here are illustrative — examples are validated
+# structurally, and reference resolution belongs to the semantic phase.
 specVersion: v1
 kind: BLUEPRINT
 metadata:
@@ -10,7 +15,7 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
   parameters: {}

specifications/blueprint/v1/examples/published-reference.yaml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://schemas.musher.dev/blueprint/v1/blueprint.schema.json
+#
+# The published reference form. `component` is the UUID of a component the
+# platform already holds, and `componentVersion` pins the lineage version to
+# deploy — required here, because no document on disk carries it.
+#
+# The same field carries both forms; the shape of the value selects the
+# resolver. A local reference would begin `./` or `../`, and must not carry a
+# `componentVersion`.
+specVersion: v1
+kind: BLUEPRINT
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  components:
+    db:
+      component: 550e8400-e29b-41d4-a716-446655440000
+      componentVersion: 3
+      size: general.standard.small
+      connections: {}
+  parameters: {}

specifications/blueprint/v1/examples/web-and-database.yaml

@@ -3,6 +3,9 @@
 # Two components wired together. Connections are consumer-anchored: the `web`
 # node declares what it consumes and from which role, so a component never
 # needs to know who will depend on it.
+#
+# The two nodes show that a repo-local reference does not mandate a directory
+# layout — `db` names a document under `components/`, `web` a flat sibling.
 specVersion: v1
 kind: BLUEPRINT
 metadata:
@@ -11,11 +14,11 @@ metadata:
 spec:
   components:
     db:
-      component: postgres
+      component: ./components/postgres.yaml
       size: general.standard.small
       connections: {}
     web:
-      component: web-server
+      component: ./component-web-server.yaml
       size: general.standard.small
       connections:
         DATABASE_URL: