-
Notifications
You must be signed in to change notification settings - Fork 0
feat: Phase 3 leftovers — Saga kind, catalog smoke, Cycle card #4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
ec02d81
feat(saga): add Saga custom kind (Git-backed narrated AAR) + seed + A…
Cervator 042514b
test(catalog): add make smoke-catalog — real Cycle+Saga ingestion smoke
Cervator 82a476f
feat(frontend): curated Cycle overview card (new frontend system exte…
Cervator eb121c0
chore(make): force test-app single-run + fold tsc into the ci gate
Cervator c2471a4
fix(phase3): address CR #4 review — ref links, saga ref test, smoke h…
Cervator a763719
test(smoke): structural jq relation checks (CR #4 Copilot)
Cervator 12289b9
fix(phase3): address CR #4 round 2 — safe ref parse, ci-gate doc, smo…
Cervator File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # Saga: a Git-backed catalog kind for narrated effort records | ||
|
|
||
| - Status: accepted | ||
| - Date: 2026-07-06 | ||
| - Deciders: Cervator, Claude (Opus 4.8) | ||
|
|
||
| ## Context and Problem Statement | ||
|
|
||
| The two-family model (ADR 0007) pairs the structured/ingestable `Cycle` with a narrated/authored counterpart: an After-Action-Report a human *writes* about an effort — a season, a talent show, a fundraiser. Backstage has no home for such narrative, and cramming append-only history into a refreshable catalog node fights the catalog. | ||
|
|
||
| ## Considered Options | ||
|
|
||
| - No kind — keep narratives as loose docs / TechDocs only. | ||
| - A `Saga` kind whose narrative body lives in the Backstage DB. | ||
| - A `Saga` kind that is a thin index entity, with the narrative body in Git. | ||
|
|
||
| ## Decision Outcome | ||
|
|
||
| Chosen: a custom **`Saga`** kind (`apiVersion: siliconsaga.org/v1alpha1`) that is a **thin, Git-backed index entity**. The narrative body is a markdown file in the org's repo, referenced by the required `siliconsaga.org/saga-doc` annotation; the entity carries `spec.skald` (the authoring User — flair for "author"), `spec.timeframe`, `spec.touches` (entity refs the Saga narrates), and optional `spec.owner`. A `SagaProcessor` (new-backend-system catalog module) validates these and emits **built-in** relations: `spec.skald`/`spec.owner` → `ownedBy`/`ownerOf`, and `spec.touches[]` → `dependsOn`/`dependencyOf`. | ||
|
|
||
| ### Consequences | ||
|
|
||
| - Good: nothing unique lives only in Backstage's DB — both the prose and the entity descriptor are Git files; the DB is a rebuildable cache. | ||
| - Good: reuses built-in relation types, so the catalog graph shows what a Saga touched with no bespoke wiring. | ||
| - A `Saga` is distinct from a `Cycle`: a season always exists as a `Cycle`; it becomes a `Saga` only if a Skald writes one (zero, one, or many per effort). | ||
| - **Deferred:** the authoring UX (catalog-backed `EntityPicker`s for `touches`) and blog/TechDocs-style rendering of `saga.md`. This ADR covers the catalog kind, not the reader/authoring surface — the `Saga` renders on the default entity page for now. | ||
|
|
||
| See ADR [0007](0007-cycle-custom-kind.md) (Cycle / two-family model) and the design doc §5. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # The Saga of MTL Soccer, Spring 2026 | ||
|
|
||
| > Skald: @guest · Season: 2026-03-01 → 2026-06-15 | ||
|
|
||
| A narrated After-Action-Report for the Spring 2026 MTL soccer season — the kind of | ||
| account no scrape produces, only a human writes. This is a placeholder narrative | ||
| that demonstrates the Git-backed `Saga` shape: the prose lives here in the repo, | ||
| the catalog `Saga` entity (in `../mtl.yaml`) points at it via the | ||
| `siliconsaga.org/saga-doc` annotation and links what it touched via `spec.touches`. | ||
|
|
||
| ## What happened | ||
|
|
||
| _(Write the story here: how the season went, notable matches, weather woes, the | ||
| volunteers who carried it, what to do differently next time.)_ | ||
|
|
||
| ## Retrospective | ||
|
|
||
| _(The Saga can simply be the retrospective — what worked, what didn't, lessons for | ||
| the next Skald.)_ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,8 @@ | ||
| import { createApp } from '@backstage/frontend-defaults'; | ||
| import catalogPlugin from '@backstage/plugin-catalog/alpha'; | ||
| import { navModule } from './modules/nav'; | ||
| import { cycleModule } from './modules/cycle'; | ||
|
|
||
| export default createApp({ | ||
| features: [catalogPlugin, navModule], | ||
| features: [catalogPlugin, navModule, cycleModule], | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| import { InfoCard, StructuredMetadataTable } from '@backstage/core-components'; | ||
| import { | ||
| EntityRefLink, | ||
| EntityRefLinks, | ||
| useEntity, | ||
| } from '@backstage/plugin-catalog-react'; | ||
| import { CompoundEntityRef, parseEntityRef } from '@backstage/catalog-model'; | ||
|
|
||
| type CycleSpec = { | ||
| type?: string; | ||
| timeframe?: { start?: string; end?: string }; | ||
| of?: string; | ||
| owner?: string; | ||
| happensAt?: string[]; | ||
| }; | ||
|
|
||
| // parseEntityRef throws on a malformed ref; never let a bad seed value break the | ||
| // card render — fall back to the dash placeholder instead. | ||
| const safeRef = ( | ||
| ref: string, | ||
| defaultKind: string, | ||
| ): CompoundEntityRef | undefined => { | ||
| try { | ||
| return parseEntityRef(ref, { defaultKind, defaultNamespace: 'default' }); | ||
| } catch { | ||
| return undefined; | ||
| } | ||
| }; | ||
|
|
||
| /** | ||
| * Curated overview card for the custom `Cycle` kind — surfaces the fields the | ||
| * default entity page buries: the type, the timeframe, and what the Cycle is | ||
| * of / happens at (rendered as clickable catalog links). Occurrences (matches, | ||
| * deployments) are not modelled as entities, so they are not shown here. | ||
| */ | ||
| export const CycleOverviewCard = () => { | ||
| const { entity } = useEntity(); | ||
| const spec = (entity.spec ?? {}) as unknown as CycleSpec; | ||
| const tf = spec.timeframe ?? {}; | ||
|
|
||
| const ofRef = spec.of ? safeRef(spec.of, 'Group') : undefined; | ||
| const happensAtRefs = (Array.isArray(spec.happensAt) ? spec.happensAt : []) | ||
| .map(t => safeRef(t, 'Resource')) | ||
| .filter((r): r is CompoundEntityRef => r !== undefined); | ||
|
|
||
| const metadata: Record<string, string | JSX.Element> = { | ||
| Type: spec.type ?? '—', | ||
| Timeframe: tf.start && tf.end ? `${tf.start} → ${tf.end}` : '—', | ||
| 'Part of': ofRef ? <EntityRefLink entityRef={ofRef} /> : '—', | ||
| 'Happens at': happensAtRefs.length > 0 | ||
| ? <EntityRefLinks entityRefs={happensAtRefs} /> | ||
| : '—', | ||
| }; | ||
|
|
||
| return ( | ||
| <InfoCard title="Cycle"> | ||
| <StructuredMetadataTable metadata={metadata} /> | ||
| </InfoCard> | ||
| ); | ||
| }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| import { createFrontendModule } from '@backstage/frontend-plugin-api'; | ||
| import { EntityCardBlueprint } from '@backstage/plugin-catalog-react/alpha'; | ||
|
|
||
| // A curated info-card on the entity Overview, shown only for `kind: Cycle`. | ||
| // Attaches to the catalog default overview automatically (EntityCardBlueprint | ||
| // attachTo: entity-content:catalog/overview) and is gated by the filter. | ||
| const cycleOverviewCard = EntityCardBlueprint.make({ | ||
| name: 'cycle', | ||
| params: { | ||
| filter: { kind: 'cycle' }, | ||
| loader: () => import('./CycleCard').then(m => <m.CycleOverviewCard />), | ||
| }, | ||
| }); | ||
|
|
||
| export const cycleModule = createFrontendModule({ | ||
| pluginId: 'app', | ||
| extensions: [cycleOverviewCard], | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
118 changes: 118 additions & 0 deletions
118
packages/backend/src/modules/saga/SagaProcessor.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| import { Entity } from '@backstage/catalog-model'; | ||
| import { CatalogProcessorResult } from '@backstage/plugin-catalog-node'; | ||
| import { SagaProcessor } from './SagaProcessor'; | ||
|
|
||
| const saga = ( | ||
| opts: { spec?: unknown; annotations?: Record<string, string> } = {}, | ||
| ): Entity => ({ | ||
| apiVersion: 'siliconsaga.org/v1alpha1', | ||
| kind: 'Saga', | ||
| metadata: { | ||
| name: 'saga-soccer-2026-spring', | ||
| annotations: | ||
| opts.annotations ?? { | ||
| 'siliconsaga.org/saga-doc': './sagas/soccer-2026-spring.md', | ||
| }, | ||
| }, | ||
| spec: opts.spec as Entity['spec'], | ||
| }); | ||
|
|
||
| const validSpec = { | ||
| skald: 'user:default/guest', | ||
| timeframe: { start: '2026-03-01', end: '2026-06-15' }, | ||
| touches: [ | ||
| 'cycle:default/soccer-2026-spring', | ||
| 'group:default/mtl-soccer', | ||
| 'resource:default/field-1', | ||
| ], | ||
| owner: 'group:default/mtl-soccer', | ||
| }; | ||
|
|
||
| describe('SagaProcessor.validateEntityKind', () => { | ||
| const p = new SagaProcessor(); | ||
|
|
||
| it('accepts a valid Saga', async () => { | ||
| await expect(p.validateEntityKind(saga({ spec: validSpec }))).resolves.toBe(true); | ||
| }); | ||
|
|
||
| it('ignores non-Saga kinds', async () => { | ||
| const c: Entity = { | ||
| apiVersion: 'backstage.io/v1alpha1', | ||
| kind: 'Component', | ||
| metadata: { name: 'x' }, | ||
| }; | ||
| await expect(p.validateEntityKind(c)).resolves.toBe(false); | ||
| }); | ||
|
|
||
| it('rejects a Saga missing skald', async () => { | ||
| const { skald: _drop, ...noSkald } = validSpec; | ||
| await expect(p.validateEntityKind(saga({ spec: noSkald }))).rejects.toThrow( | ||
| /spec\.skald is required/, | ||
| ); | ||
| }); | ||
|
|
||
| it('rejects a Saga with empty touches', async () => { | ||
| await expect( | ||
| p.validateEntityKind(saga({ spec: { ...validSpec, touches: [] } })), | ||
| ).rejects.toThrow(/spec\.touches/); | ||
| }); | ||
|
|
||
| it('rejects a Saga missing the saga-doc annotation', async () => { | ||
| await expect( | ||
| p.validateEntityKind(saga({ spec: validSpec, annotations: {} })), | ||
| ).rejects.toThrow(/saga-doc/); | ||
| }); | ||
|
|
||
| it('rejects a Saga with a malformed skald ref', async () => { | ||
| await expect( | ||
| p.validateEntityKind(saga({ spec: { ...validSpec, skald: 'user:default/' } })), | ||
| ).rejects.toThrow(/spec\.skald is not a valid entity ref/); | ||
| }); | ||
| }); | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| describe('SagaProcessor.postProcessEntity', () => { | ||
| const p = new SagaProcessor(); | ||
|
|
||
| it('emits ownedBy (skald + owner) and dependsOn (touches)', async () => { | ||
| const emitted: CatalogProcessorResult[] = []; | ||
| await p.postProcessEntity( | ||
| saga({ spec: validSpec }), | ||
| { type: 'file', target: 'examples/mtl.yaml' } as any, | ||
| r => emitted.push(r), | ||
| ); | ||
| const rels = emitted | ||
| .filter(r => r.type === 'relation') | ||
| .map(r => (r as any).relation); | ||
|
|
||
| expect(rels).toEqual( | ||
| expect.arrayContaining([ | ||
| expect.objectContaining({ | ||
| type: 'ownedBy', | ||
| target: expect.objectContaining({ kind: 'user', name: 'guest' }), | ||
| }), | ||
| expect.objectContaining({ | ||
| type: 'ownedBy', | ||
| target: expect.objectContaining({ kind: 'group', name: 'mtl-soccer' }), | ||
| }), | ||
| expect.objectContaining({ | ||
| type: 'dependsOn', | ||
| target: expect.objectContaining({ kind: 'cycle', name: 'soccer-2026-spring' }), | ||
| }), | ||
| expect.objectContaining({ | ||
| type: 'dependsOn', | ||
| target: expect.objectContaining({ kind: 'resource', name: 'field-1' }), | ||
| }), | ||
| ]), | ||
| ); | ||
| }); | ||
|
|
||
| it('emits nothing for non-Saga kinds', async () => { | ||
| const emitted: CatalogProcessorResult[] = []; | ||
| await p.postProcessEntity( | ||
| { apiVersion: 'backstage.io/v1alpha1', kind: 'Component', metadata: { name: 'x' } }, | ||
| { type: 'file', target: 'x' } as any, | ||
| r => emitted.push(r), | ||
| ); | ||
| expect(emitted).toHaveLength(0); | ||
| }); | ||
| }); | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.