Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
37 changes: 27 additions & 10 deletions builder/set.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -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();
Expand Down Expand Up @@ -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) };

Expand Down Expand Up @@ -271,7 +287,8 @@ export function mergeModels(set, models) {
features,
security,
quality,
compliance: [...obligations.values()],
compliance: [...obligations.values(), ...systemObligations],
system,
};
}

Expand Down
159 changes: 159 additions & 0 deletions builder/system.mjs
Original file line number Diff line number Diff line change
@@ -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) };
}
43 changes: 43 additions & 0 deletions builder/test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
Loading
Loading