Architecture decisions: files, diagram references, views and panels
- *.archify-decision files: id (unique, words), title, status, date, elements, diagrams, supersedes, and prose; parsed, merged and link-checked in the model index; diagnostics on the file - diagrams point at decisions with decisions: [...] on the diagram, nodes and edges; stripped before Archify, unknown ids reported, completion, hover and go-to-definition for the ids and for elements/diagrams/ supersedes in decision files - Decisions panel on the main.archify page; Decisions rail panel under a diagram (hover lights up the node or connection); decisions on element cards and in the element dialog; decision view for the file, with a lost-model note outside a model - Archify | New Decision… command and template; editor schemas; the three New Model examples carry decisions; docs, changelog, 0.8.0
This commit is contained in:
root-at-skic committed
1 parent
33ebdd6328
commit
ebf320a023
49 files changed
+1637
-55
No files matched your search
@@ -0,0 +1,183 @@
|
||||
import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
|
||||
import { ModelProblem, Registry } from './format';
|
||||
|
||||
/**
|
||||
* Architecture decisions of a model (see docs/model.md): one
|
||||
* `*.archify-decision` file per decision, anywhere under the model root.
|
||||
* Pure functions, no VS Code imports.
|
||||
*/
|
||||
|
||||
export const DECISION_EXT = '.archify-decision';
|
||||
export const DECISION_STATUSES = ['proposed', 'accepted', 'superseded', 'rejected'] as const;
|
||||
export type DecisionStatus = (typeof DECISION_STATUSES)[number];
|
||||
|
||||
export interface Decision {
|
||||
id: string;
|
||||
title?: string;
|
||||
status?: string;
|
||||
date?: string;
|
||||
/** Registry element ids the decision is about. */
|
||||
elements: string[];
|
||||
/** Diagram paths (relative to the model root) the decision names. */
|
||||
diagrams: string[];
|
||||
/** Ids of older decisions this one replaces. */
|
||||
supersedes: string[];
|
||||
context?: string;
|
||||
decision?: string;
|
||||
consequences?: string;
|
||||
/** Decision file relative to the model root, and 0-based lines for diagnostics. */
|
||||
file: string;
|
||||
line: number;
|
||||
lines: { id: number; status: number; elements: number[]; diagrams: number[]; supersedes: number[] };
|
||||
}
|
||||
|
||||
export function isDecisionFile(fileName: string): boolean {
|
||||
return fileName.endsWith(DECISION_EXT);
|
||||
}
|
||||
|
||||
const str = (v: unknown): string | undefined => (typeof v === 'string' && v.trim().length > 0 ? v : v !== undefined && v !== null && typeof v !== 'object' ? String(v) : undefined);
|
||||
|
||||
/** "OpenSearch for product search" → "opensearch-for-product-search". */
|
||||
export function slugify(title: string): string {
|
||||
const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
|
||||
return slug || 'decision';
|
||||
}
|
||||
|
||||
/** Parses one decision file. Problems carry 0-based lines. */
|
||||
export function parseDecision(text: string, file: string): { decision?: Decision; problems: ModelProblem[] } {
|
||||
const problems: ModelProblem[] = [];
|
||||
const doc = parseDocument(text, { prettyErrors: false, uniqueKeys: false });
|
||||
for (const error of doc.errors) {
|
||||
problems.push({ message: `Decision is not valid YAML: ${error.message.split('\n')[0]}`, severity: 'error', file, line: error.linePos?.[0].line ? error.linePos[0].line - 1 : 0 });
|
||||
}
|
||||
if (doc.errors.length) return { problems };
|
||||
const lineOf = (offset: number | undefined) => (offset === undefined ? 0 : text.slice(0, offset).split('\n').length - 1);
|
||||
const root = doc.contents;
|
||||
if (!isMap(root)) {
|
||||
problems.push({ message: 'A decision file is a mapping with a "decision" block and context, decision and consequences.', severity: 'error', file, line: 0 });
|
||||
return { problems };
|
||||
}
|
||||
const headNode = root.get('decision', true);
|
||||
if (!isMap(headNode)) {
|
||||
problems.push({ message: 'A decision needs a "decision" block with id, title and status.', severity: 'error', file, line: 0, pointer: '/decision' });
|
||||
return { problems };
|
||||
}
|
||||
const headPair = root.items.find((pair) => isScalar(pair.key) && pair.key.value === 'decision');
|
||||
const headLine = headPair && isScalar(headPair.key) ? lineOf(headPair.key.range?.[0]) : 0;
|
||||
const keyLine = (key: string) => {
|
||||
const pair = headNode.items.find((p) => isScalar(p.key) && p.key.value === key);
|
||||
return pair && isScalar(pair.key) ? lineOf(pair.key.range?.[0]) : headLine;
|
||||
};
|
||||
const list = (key: string): { values: string[]; lines: number[] } => {
|
||||
const node = headNode.get(key, true);
|
||||
const values: string[] = [];
|
||||
const lines: number[] = [];
|
||||
if (isSeq(node)) {
|
||||
for (const item of node.items) {
|
||||
if (!isScalar(item)) continue;
|
||||
if (typeof item.value === 'number') {
|
||||
problems.push({ message: `"${item.value}" in ${key} is a number to YAML. Quote it or use words.`, severity: 'error', file, line: lineOf(item.range?.[0]), pointer: `/decision/${key}` });
|
||||
continue;
|
||||
}
|
||||
if (str(item.value)) {
|
||||
values.push(String(item.value));
|
||||
lines.push(lineOf(item.range?.[0]));
|
||||
}
|
||||
}
|
||||
} else if (node !== undefined) {
|
||||
problems.push({ message: `"${key}" must be a list.`, severity: 'error', file, line: keyLine(key), pointer: `/decision/${key}` });
|
||||
}
|
||||
return { values, lines };
|
||||
};
|
||||
const head = headNode.toJSON() as Record<string, unknown>;
|
||||
if (typeof head.id === 'number') {
|
||||
problems.push({ message: `decision.id ${head.id} is a number to YAML (0001 becomes 1). Quote it ("${head.id}") or use words.`, severity: 'error', file, line: keyLine('id'), pointer: '/decision/id' });
|
||||
return { problems };
|
||||
}
|
||||
const id = str(head.id);
|
||||
if (!id) {
|
||||
problems.push({ message: 'decision.id is missing.', severity: 'error', file, line: headLine, pointer: '/decision/id' });
|
||||
return { problems };
|
||||
}
|
||||
const status = str(head.status);
|
||||
if (status && !(DECISION_STATUSES as readonly string[]).includes(status)) {
|
||||
problems.push({ message: `Unknown status "${status}"; one of ${DECISION_STATUSES.join(', ')}.`, severity: 'error', file, line: keyLine('status'), pointer: '/decision/status' });
|
||||
}
|
||||
const elements = list('elements');
|
||||
const diagrams = list('diagrams');
|
||||
const supersedes = list('supersedes');
|
||||
const body = root.toJSON() as Record<string, unknown>;
|
||||
return {
|
||||
problems,
|
||||
decision: {
|
||||
id,
|
||||
title: str(head.title),
|
||||
status,
|
||||
date: str(head.date),
|
||||
elements: elements.values,
|
||||
diagrams: diagrams.values,
|
||||
supersedes: supersedes.values,
|
||||
context: str(body.context),
|
||||
decision: str(body.decision),
|
||||
consequences: str(body.consequences),
|
||||
file,
|
||||
line: headLine,
|
||||
lines: { id: keyLine('id'), status: keyLine('status'), elements: elements.lines, diagrams: diagrams.lines, supersedes: supersedes.lines },
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export interface DecisionSet {
|
||||
decisions: Map<string, Decision>;
|
||||
files: string[];
|
||||
problems: ModelProblem[];
|
||||
}
|
||||
|
||||
/** Merges parsed decision files; an id used twice is an error on the second file. */
|
||||
export function mergeDecisions(parts: { file: string; decision?: Decision; problems: ModelProblem[] }[]): DecisionSet {
|
||||
const decisions = new Map<string, Decision>();
|
||||
const problems: ModelProblem[] = [];
|
||||
for (const part of parts) {
|
||||
problems.push(...part.problems);
|
||||
if (!part.decision) continue;
|
||||
const existing = decisions.get(part.decision.id);
|
||||
if (existing) {
|
||||
problems.push({ message: `Decision "${part.decision.id}" is defined twice (also in ${existing.file}).`, severity: 'error', file: part.file, line: part.decision.lines.id });
|
||||
continue;
|
||||
}
|
||||
decisions.set(part.decision.id, part.decision);
|
||||
}
|
||||
return { decisions, files: parts.map((p) => p.file), problems };
|
||||
}
|
||||
|
||||
/** The status the pages show: a decision another one supersedes is superseded, whatever its file says. */
|
||||
export function effectiveStatus(decision: Decision, all: Map<string, Decision>): { status: string; supersededBy?: string } {
|
||||
for (const other of all.values()) {
|
||||
if (other !== decision && other.supersedes.includes(decision.id) && other.status !== 'rejected') return { status: 'superseded', supersededBy: other.id };
|
||||
}
|
||||
return { status: decision.status ?? 'proposed' };
|
||||
}
|
||||
|
||||
/** Link checks across the model: elements, diagrams and supersedes must exist. */
|
||||
export function validateDecisions(set: DecisionSet, registry: Registry | undefined, diagramPaths: Set<string>): ModelProblem[] {
|
||||
const problems: ModelProblem[] = [];
|
||||
for (const d of set.decisions.values()) {
|
||||
d.elements.forEach((id, i) => {
|
||||
if (!registry?.elements.has(id)) problems.push({ message: `Unknown element "${id}": no registry of this model defines it.`, severity: 'error', file: d.file, line: d.lines.elements[i], pointer: `/decision/elements/${i}` });
|
||||
});
|
||||
d.diagrams.forEach((path, i) => {
|
||||
if (!diagramPaths.has(path)) problems.push({ message: `Diagram "${path}" does not exist in this model.`, severity: 'error', file: d.file, line: d.lines.diagrams[i], pointer: `/decision/diagrams/${i}` });
|
||||
});
|
||||
d.supersedes.forEach((id, i) => {
|
||||
if (!set.decisions.has(id)) problems.push({ message: `Decision "${id}" (in supersedes) does not exist in this model.`, severity: 'error', file: d.file, line: d.lines.supersedes[i], pointer: `/decision/supersedes/${i}` });
|
||||
else if (id === d.id) problems.push({ message: 'A decision cannot supersede itself.', severity: 'error', file: d.file, line: d.lines.supersedes[i], pointer: `/decision/supersedes/${i}` });
|
||||
});
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/** Sort for lists: live decisions newest first, superseded and rejected last. */
|
||||
export function sortDecisions(decisions: Decision[], all: Map<string, Decision>): Decision[] {
|
||||
const rank = (d: Decision) => (['superseded', 'rejected'].includes(effectiveStatus(d, all).status) ? 1 : 0);
|
||||
return [...decisions].sort((a, b) => rank(a) - rank(b) || (b.date ?? '').localeCompare(a.date ?? '') || a.id.localeCompare(b.id));
|
||||
}
|
||||
Reference in new issue
Block a user