diff --git a/CONFORMANCE.md b/CONFORMANCE.md index ebfbfa5..f090dd9 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -52,6 +52,7 @@ model does not sanction. | `DR-51` | `build` | Every Prism facet has a concept page that explains the facet from its standard and shows how each case study declares it, with record counts read from the subjects | | `DR-52` | `build` | Every old learn/ address redirects to the page that replaced it, so no published link breaks | | `DR-53` | `build` | Every subject pin moves only forward, to the newest main commit whose gate workflow passed, and the catalogs are regenerated from the new pins without anyone editing them | +| `DR-54` | `build` | build-set describes the set as one system when the set has a system record: an OPM system diagram (main process, beneficiary and the attribute it changes, instruments, inputs, results) and its zoom into parts, each part zooming into the decisions it holds, with every app a part's exactly once, a part no app realizes stating what it owes, and one compliance obligation per standard the system names; a record missing any of these is refused | ## fidelity diff --git a/builder/set.mjs b/builder/set.mjs index 66ce4ce..b343cc9 100644 --- a/builder/set.mjs +++ b/builder/set.mjs @@ -33,6 +33,7 @@ import { listDefinitions, reflow } from './lean.mjs'; import { renderMachineModel, renderMachineProofs } from './machine.mjs'; import { deriveModel } from './model.mjs'; import { DFD_OF, STRIDE, STRIDE_PER_ELEMENT, STRIDE_TEXT } from './prompt.mjs'; +import { addSystem, readSystem } from './system.mjs'; export const SET_SCHEMA = 'prism/prompt-set/1'; @@ -102,6 +103,9 @@ function idPrefixes(models, taken = new Set()) { /** One model of the facets of every app in the set: the records each app derives, with what they share made one. */ export function mergeModels(set, models) { const P = 'Architecture::'; + let systemObligations = []; + // A part names its decisions as the set lists their prompts, without `.prompt.json`. + const stems = (set.prompts ?? []).map((f) => String(f).replace(/\.prompt\.json$/, '')); const rename = new Map(); // ---- Architecture: shared stakeholders and components become one record. const stakeholders = new Map(); @@ -167,20 +171,32 @@ export function mergeModels(set, models) { for (const m of models) for (const c of m.architecture.concerns) concernNames.set(c.name, (concernNames.get(c.name) ?? 0) + 1); for (const m of models) for (const c of m.architecture.concerns) if (concernNames.get(c.name) > 1) c.name = `${c.name}: ${m.title}`; - const architecture = { - stakeholders: indexed([...stakeholders.values()]), - concerns: indexed(models.flatMap((m) => m.architecture.concerns)), - components: indexed(allComponents), - edges: indexed([...edges.values()]), - viewpoints: indexed(models.flatMap((m) => m.architecture.viewpoints)), - views: indexed(models.flatMap((m) => m.architecture.views)), - }; - // ---- Design: every app's views, with references to merged records renamed. const keys = ['processes', 'states', 'views', 'opmThings', 'opmStates', 'opmLinks', 'opmZooms', 'umlComponents', 'umlConnectors', 'lifelines', 'messages', 'umlStates', 'transitions']; const design = Object.fromEntries(keys.map((k) => [k, models.flatMap((m) => m.design[k])])); renameStrings(design, rename); + // ---- The system as a whole (system.mjs): its records join the merged ones before they are indexed. + const top = { stakeholders: [...stakeholders.values()], concerns: models.flatMap((m) => m.architecture.concerns), components: allComponents, edges: [...edges.values()], viewpoints: models.flatMap((m) => m.architecture.viewpoints), views: models.flatMap((m) => m.architecture.views) }; + const system = set.system + ? addSystem(readSystem(set.system, stems), { + ...top, + design, + compliance: (systemObligations = []), + shared: (key) => components.get(key), + decide: (stem) => models[stems.indexOf(stem)].design.processes.find((p) => p.name === 'Decide').decl, + }) + : null; + + const architecture = { + stakeholders: indexed(top.stakeholders), + concerns: indexed(top.concerns), + components: indexed(top.components), + edges: indexed(top.edges), + viewpoints: indexed(top.viewpoints), + views: indexed(top.views), + }; + // ---- Features and journeys. const features = { features: models.flatMap((m) => m.features.features), journeys: models.flatMap((m) => m.features.journeys) }; @@ -271,7 +287,8 @@ export function mergeModels(set, models) { features, security, quality, - compliance: [...obligations.values()], + compliance: [...obligations.values(), ...systemObligations], + system, }; } diff --git a/builder/system.mjs b/builder/system.mjs new file mode 100644 index 0000000..486a871 --- /dev/null +++ b/builder/system.mjs @@ -0,0 +1,159 @@ +/** + * The system as a whole: the top of a set's architecture description (ISO/IEC/IEEE + * 42010) and its OPM system diagram (ISO 19450), from the set's `system` record. + * + * Without it a set describes only its decisions, each with its own OPM view. The + * `system` record says what the decisions are parts of: the system's main process, + * its beneficiary and the attribute of the beneficiary it changes (from one state + * to another), the objects the main process uses (instruments), takes in (inputs) + * and makes (results), and the parts the main process zooms into. Every decision of + * the set is a part's, exactly once; a part no decision realizes yet states what it + * owes. Each standard the system answers to is named once, by its key in the + * repository's standards register, with what it settles for the system. + * + * The records it adds: a stakeholder (the beneficiary), a concern (the attribute), + * a viewpoint and a view; components for the system, the beneficiary, every input + * and result it names (a shared component, such as the browser, by its key); the + * main process, one process per part, and the attribute's two states; two OPM views, + * the system diagram and its zoom (main process into parts, each part into the + * Decide process of every decision it holds); one compliance obligation per standard. + */ +import { SpecError } from './vendor/prism-code/src/journey/spec.mjs'; + +const SHARED = ['browser', 'build', 'host', 'source']; +const KINDS = ['service', 'database', 'externalSystem', 'cliAdapter', 'staticSite', 'releaseBinary']; +const pascal = (s) => + String(s) + .split(/[^A-Za-z0-9]+/) + .filter(Boolean) + .map((w) => w[0].toUpperCase() + w.slice(1)) + .join('') || 'X'; +const text = (v, where) => { + if (typeof v !== 'string' || !v.trim()) throw new SpecError(`The system needs \`${where}\`.`, `system.${where}`); + return v; +}; +const named = (v, where) => ({ name: text(v?.name, `${where}.name`), text: text(v?.text, `${where}.text`) }); + +/** The `system` record, checked against the set's apps (by their prompt's name in the set, without `.prompt.json`). */ +export function readSystem(system, apps) { + if (system === undefined) return null; + const s = { + name: text(system.name, 'name'), + text: text(system.text, 'text'), + frame: text(system.frame, 'frame'), + mainProcess: named(system.mainProcess, 'mainProcess'), + beneficiary: named(system.beneficiary, 'beneficiary'), + attribute: { ...named(system.attribute, 'attribute'), from: named(system.attribute?.from, 'attribute.from'), to: named(system.attribute?.to, 'attribute.to') }, + }; + const objects = (key) => { + const list = system[key] ?? []; + if (!Array.isArray(list) || !list.length) throw new SpecError(`The system's main process needs at least one of \`${key}\`.`, `system.${key}`); + return list.map((o, i) => { + if (o?.component !== undefined) { + if (!SHARED.includes(o.component)) throw new SpecError(`\`${key}[${i}].component\` is one of ${SHARED.join(', ')}.`, `system.${key}`); + return { shared: o.component }; + } + if (!KINDS.includes(o?.kind)) throw new SpecError(`\`${key}[${i}].kind\` is one of ${KINDS.join(', ')}.`, `system.${key}`); + return { ...named(o, `${key}[${i}]`), kind: o.kind }; + }); + }; + s.instruments = objects('instruments'); + s.inputs = objects('inputs'); + s.results = objects('results'); + if (!Array.isArray(system.parts) || !system.parts.length) throw new SpecError('The system names its parts.', 'system.parts'); + const held = new Map(); + s.parts = system.parts.map((p, i) => { + const part = { ...named(p, `parts[${i}]`), process: text(p.process, `parts[${i}].process`), decisions: p.decisions ?? [] }; + if (!Array.isArray(part.decisions)) throw new SpecError(`\`parts[${i}].decisions\` lists app names.`, 'system.parts'); + for (const d of part.decisions) { + if (!apps.includes(d)) throw new SpecError(`The part ${part.name} holds ${d}, which is no app of the set.`, 'system.parts'); + if (held.has(d)) throw new SpecError(`${d} is a part of both ${held.get(d)} and ${part.name}.`, 'system.parts'); + held.set(d, part.name); + } + if (part.decisions.length && p.owed !== undefined) throw new SpecError(`The part ${part.name} holds decisions, so it owes none.`, 'system.parts'); + if (!part.decisions.length) part.owed = text(p.owed, `parts[${i}].owed`); + return part; + }); + const loose = apps.filter((a) => !held.has(a)); + if (loose.length) throw new SpecError(`Every app is a part of the system; ${loose.join(', ')} ${loose.length === 1 ? 'is' : 'are'} not.`, 'system.parts'); + if (new Set(s.parts.map((p) => p.name)).size !== s.parts.length) throw new SpecError('Two parts share a name.', 'system.parts'); + s.standards = (system.standards ?? []).map((x, i) => ({ key: text(x?.key, `standards[${i}].key`), title: text(x?.title, `standards[${i}].title`), settles: text(x?.settles, `standards[${i}].settles`) })); + if (new Set(s.standards.map((x) => x.key)).size !== s.standards.length) throw new SpecError('A standard is named once.', 'system.standards'); + return s; +} + +/** + * The system's records, added to a merged model in place, before its records are + * indexed. `shared` maps a shared component key to its merged component, and + * `decide` maps an app name to its Decide process declaration. + */ +export function addSystem(s, { stakeholders, concerns, components, edges, viewpoints, views, design, compliance, shared, decide }) { + const A = (c) => `Architecture::${c.decl}`; + const D = (decl) => `Design::${decl}`; + const beneficiary = { decl: `stakeholder${pascal(s.beneficiary.name)}`, name: s.beneficiary.name, text: s.beneficiary.text }; + stakeholders.push(beneficiary); + const concern = { decl: `concernSystem${pascal(s.attribute.name)}`, name: s.attribute.name, text: s.attribute.text, model: 'component' }; + concerns.push(concern); + const viewpoint = { decl: 'viewpointSystem', stakeholder: beneficiary, concern, modelKind: 0 }; + viewpoints.push(viewpoint); + views.push({ decl: 'viewSystem', viewpoint, modelKind: 0 }); + + const component = (o, fallback) => { + if (o.shared) { + const c = shared(o.shared); + if (!c) throw new SpecError(`No app of the set declares the shared component ${o.shared}.`, 'system'); + return c; + } + const c = { decl: `componentSystem${pascal(o.name)}`, key: `system:${o.name}`, name: o.name, kind: o.kind ?? fallback, text: o.text }; + components.push(c); + return c; + }; + const whole = component({ name: s.name, kind: 'service', text: s.text }); + const person = component({ name: s.beneficiary.name, kind: 'externalSystem', text: s.beneficiary.text }); + const instruments = s.instruments.map((o) => component(o)); + const inputs = s.inputs.map((o) => component(o)); + const results = s.results.map((o) => component(o)); + const edge = (from, to, kind) => edges.push({ decl: `edgeSystem${pascal(`${from.name} to ${to.name}`)}`, from, to, kind }); + for (const c of inputs) edge(c, whole, 'dataFlow'); + for (const c of results) edge(whole, c, 'dataFlow'); + edge(whole, person, 'dataFlow'); + edge(person, whole, 'controlFlow'); + + const main = { decl: `processSystem${pascal(s.mainProcess.name)}`, name: s.mainProcess.name, owner: whole, text: s.mainProcess.text }; + const parts = s.parts.map((p) => ({ ...p, decl: `processSystemPart${pascal(p.name)}`, owner: whole })); + design.processes.push(main, ...parts.map((p) => ({ decl: p.decl, name: p.process, owner: whole, text: p.text }))); + const from = { decl: `stateSystem${pascal(s.attribute.from.name)}`, name: s.attribute.from.name, owner: person, text: s.attribute.from.text }; + const to = { decl: `stateSystem${pascal(s.attribute.to.name)}`, name: s.attribute.to.name, owner: person, text: s.attribute.to.text }; + design.states.push(from, to); + + const sd = { decl: 'designViewSystem', title: `${s.name}: ${s.frame}`, viewpoint, diagram: 'opmObjectProcess' }; + const sd1 = { decl: 'designViewSystemParts', title: `Zooming into ${s.mainProcess.name}`, viewpoint, diagram: 'opmObjectProcess' }; + design.views.push(sd, sd1); + const thing = (view, kind, subject, name) => design.opmThings.push({ decl: `opm${view === sd ? 'System' : 'SystemParts'}${pascal(name)}`, view, kind, subject }); + const link = (view, kind, source, target, name) => design.opmLinks.push({ decl: `opmSystem${pascal(name)}`, view, kind, source, target }); + thing(sd, 'object', A(whole), whole.name); + thing(sd, 'object', A(person), person.name); + for (const c of new Set([...instruments, ...inputs, ...results])) thing(sd, 'object', A(c), c.name); + thing(sd, 'process', D(main.decl), main.name); + design.opmStates.push(...[from, to].map((x) => ({ decl: `opmSystem${pascal(`${person.name} ${x.name}`)}`, view: sd, thing: A(person), state: D(x.decl) }))); + link(sd, 'agent', A(person), D(main.decl), `${person.name} agent`); + link(sd, 'effect', A(person), D(main.decl), `${person.name} effect`); + link(sd, 'exhibition', A(whole), D(main.decl), `${whole.name} exhibits`); + for (const c of instruments) link(sd, 'instrument', A(c), D(main.decl), `${c.name} instrument`); + for (const c of inputs) link(sd, 'consumption', A(c), D(main.decl), `${c.name} consumed`); + for (const c of results) link(sd, 'result', A(c), D(main.decl), `${c.name} result`); + + thing(sd1, 'process', D(main.decl), main.name); + parts.forEach((p, order) => { + thing(sd1, 'process', D(p.decl), p.name); + design.opmZooms.push({ decl: `opmSystemZoom${pascal(p.name)}`, view: sd1, process: D(main.decl), subprocess: D(p.decl), order }); + p.decisions.forEach((app, k) => { + thing(sd1, 'process', D(decide(app)), `${app} decide`); + design.opmZooms.push({ decl: `opmSystemZoom${pascal(`${p.name} ${app}`)}`, view: sd1, process: D(p.decl), subprocess: D(decide(app)), order: k }); + }); + }); + + for (const x of s.standards) + compliance.push({ standard: x.title, subject: `${s.name}: ${x.key}`, text: x.settles, evidence: [D(sd.decl), D(sd1.decl)] }); + return { parts, owed: parts.filter((p) => p.owed).map((p) => p.name) }; +} diff --git a/builder/test.mjs b/builder/test.mjs index 052ddea..320bdf9 100644 --- a/builder/test.mjs +++ b/builder/test.mjs @@ -406,6 +406,49 @@ const CASES = { const twinIds = twins.claims.map((c) => c.id); ok(twinIds.includes('PCL-01') && twinIds.includes('PCLI-01') && new Set(twinIds).size === twinIds.length, "a prefix an earlier app of the set holds is lengthened from the later app's last word"); }, + // A set with a system record is described as one system: an OPM system diagram at the top, zooming into its parts and their apps. + async 'DR-54'() { + const names = ['kappa-namespace-authorization', 'prismpm-container-lifecycle', 'dataflow-policy-check']; + const prompts = names.map((n) => readPrompt(JSON.parse(readFileSync(join(examples, `${n}.prompt.json`), 'utf8')))); + const system = { + name: 'Gallery', + text: 'Three gallery apps working as one system.', + frame: 'one system of three decisions', + mainProcess: { name: 'Deciding', text: 'Answering every request one of the parts takes.' }, + beneficiary: { name: 'Operator', text: 'The person the decisions serve.' }, + attribute: { name: 'Confidence', text: 'How sure the operator is of what may happen.', from: { name: 'Unsure', text: 'Unsure.' }, to: { name: 'Sure', text: 'Sure.' } }, + instruments: [{ component: 'browser' }], + inputs: [{ name: 'Requests', kind: 'externalSystem', text: 'Where requests come from.' }], + results: [{ name: 'Decision log', kind: 'database', text: 'What was decided.' }], + parts: [ + { name: 'Access', process: 'Deciding access', text: 'Who may act.', decisions: [names[0]] }, + { name: 'Lifecycle', process: 'Running containers', text: 'What a container does next.', decisions: [names[1]] }, + { name: 'Flow', process: 'Checking flows', text: 'What may flow.', decisions: [names[2]] }, + { name: 'Audit', process: 'Auditing', text: 'Looking back.', owed: 'No app decides it yet.' }, + ], + standards: [{ key: 'iso-19450', title: 'ISO/PAS 19450:2015 Object-Process Methodology', settles: 'The system diagram.' }], + }; + const set = { schema: 'prism/prompt-set/1', name: 'gallery-set', title: 'Gallery set', purpose: 'Three gallery apps in one application.', repository: 'afflom/prism-devrel', prompts: names.map((n) => `${n}.prompt.json`), system }; + const { files } = await buildSet(set, prompts, { lastModified: AT }); + const declares = (path, name) => new RegExp(`^ {2}name: ${name},$`, 'm').test(files[path]); + for (const n of ['stakeholderOperator', 'concernSystemConfidence', 'viewpointSystem', 'viewSystem', 'componentSystemGallery', 'componentSystemOperator', 'componentSystemRequests', 'componentSystemDecisionLog', 'edgeSystemRequestsToGallery', 'edgeSystemOperatorToGallery']) + ok(declares('app/src/Architecture.lex.tex', n), `Architecture declares ${n}`); + for (const n of ['designViewSystem', 'designViewSystemParts', 'processSystemDeciding', 'stateSystemUnsure', 'stateSystemSure', 'opmSystemOperatorAgent', 'opmSystemOperatorEffect', 'opmSystemBrowserInstrument', 'opmSystemRequestsConsumed', 'opmSystemDecisionLogResult', ...system.parts.flatMap((p) => [`processSystemPart${p.name}`, `opmSystemZoom${p.name}`])]) + ok(declares('app/src/Design.lex.tex', n), `Design declares ${n}`); + for (const p of system.parts.filter((x) => x.decisions)) + ok(files['app/src/Design.lex.tex'].includes(`opmSystemZoom${p.name}${p.decisions[0].split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join('')}`), `${p.name} zooms into ${p.decisions[0]}`); + ok(files['app/src/Compliance.lex.tex'].includes('subject := "Gallery: iso-19450"'), 'Compliance holds an obligation for the standard'); + const plain = await buildSet({ ...set, system: undefined }, prompts, { lastModified: AT }); + ok(!plain.files['app/src/Design.lex.tex'].includes('designViewSystem'), 'a set without a system record has no system diagram'); + const without = (k) => Object.fromEntries(Object.entries(system).filter(([key]) => key !== k)); + for (const k of ['name', 'mainProcess', 'beneficiary', 'attribute', 'instruments', 'inputs', 'results', 'parts']) await refused(() => buildSet({ ...set, system: without(k) }, prompts, { lastModified: AT }), /system/, `a system without ${k} is refused`); + const parts = (ps) => buildSet({ ...set, system: { ...system, parts: ps } }, prompts, { lastModified: AT }); + await refused(() => parts(system.parts.slice(1)), /is not|are not/, 'an app in no part is refused'); + await refused(() => parts([...system.parts, { name: 'Again', process: 'p', text: 't', decisions: [names[0]] }]), /both/, 'an app in two parts is refused'); + await refused(() => parts([...system.parts, { name: 'Empty', process: 'p', text: 't' }]), /owed/, 'a part that holds no app and owes nothing is refused'); + await refused(() => parts([...system.parts, { name: 'Ghost', process: 'p', text: 't', decisions: ['no-such-app'] }]), /no app of the set/, 'a part holding an unknown app is refused'); + await refused(() => buildSet({ ...set, system: { ...system, instruments: [{ component: 'printer' }] } }, prompts, { lastModified: AT }), /component/, 'an unknown shared component is refused'); + }, async 'DR-07'() { const good = rule30(); ok(deriveModel(good).spec.rules.length === 3, 'the Rule 30 prompt is accepted'); diff --git a/crates/devrel/tests/builder.rs b/crates/devrel/tests/builder.rs index db449b2..ab8cd79 100644 --- a/crates/devrel/tests/builder.rs +++ b/crates/devrel/tests/builder.rs @@ -120,3 +120,9 @@ fn guides_dr_21() { fn build_set_dr_22() { builder("DR-22"); } + +/// `DR-54`: Build-set describes the set as one system when the set has a system record: an OPM system diagram (main process, beneficiary and the attribute it changes, instruments, inputs, results) and its zoom into parts, each part zooming into the decisions it holds, with every app a part's exactly once, a part no app realizes stating what it owes, and one compliance obligation per standard the system names; a record missing any of these is refused +#[test] +fn build_set_system_dr_54() { + builder("DR-54"); +} diff --git a/features/suites/devrel.feature b/features/suites/devrel.feature index 48472b0..d07ea40 100644 --- a/features/suites/devrel.feature +++ b/features/suites/devrel.feature @@ -171,6 +171,13 @@ Feature: devrel And no declaration name repeats across the modules the guest compiles, and every line past 100 columns is a term or a lone name, as lexlean fmt leaves it And the router answers every vector of every app, prefixed with the app's name, as the app does, and answers its own vectors, and every claim id is distinct, each app's from the initials of its name and the facets' from the set's + @DR-54 @build + Scenario: Build-set describes the set as one system when the set has a system record: an OPM system diagram (main process, beneficiary and the attribute it changes, instruments, inputs, results) and its zoom into parts, each part zooming into the decisions it holds, with every app a part's exactly once, a part no app realizes stating what it owes, and one compliance obligation per standard the system names; a record missing any of these is refused + Given the DR-22 prompt set with a system record whose three parts hold its three apps + When builder/test.mjs DR-54 builds it, and builds it again with each role taken away + Then Architecture declares the beneficiary, the system viewpoint and the system's components, Design declares the system diagram and its zoom with the main process, every part's process and a zoom into every app's Decide process, and Compliance holds an obligation per standard + And a record without a role, with an app in no part or in two, or with a part that neither holds an app nor owes one, is refused + @DR-50 @build Scenario: Every subject in devrel/subjects.json has a case study under case-studies//, read from every facet record of the subject at its pinned commit, or at the commit being built for the self subject, and the case studies index lists every subject Given a subjects file listing a pinned subject checked out under --checkouts and this repository as the self subject diff --git a/model/ids.toml b/model/ids.toml index a2736ed..81b2ae1 100644 --- a/model/ids.toml +++ b/model/ids.toml @@ -201,6 +201,12 @@ level = "build" suite = "devrel" statement = "Every subject pin moves only forward, to the newest main commit whose gate workflow passed, and the catalogs are regenerated from the new pins without anyone editing them" +[[id]] +id = "DR-54" +level = "build" +suite = "devrel" +statement = "build-set describes the set as one system when the set has a system record: an OPM system diagram (main process, beneficiary and the attribute it changes, instruments, inputs, results) and its zoom into parts, each part zooming into the decisions it holds, with every app a part's exactly once, a part no app realizes stating what it owes, and one compliance obligation per standard the system names; a record missing any of these is refused" + [[id]] id = "FI-01" level = "build"