yarramate 0.20.0 → 0.22.0

package/dist/notation/archimate.js

@@ -0,0 +1,183 @@
+// Single source of truth for ArchiMate-inspired rendering data: layer
+// palette, aspect-driven shape tokens, per-concept-kind glyphs, and
+// per-relationship-kind line/arrow styles. Pure data + lookups, no
+// cytoscape/DOM dependency - the same zero-import discipline as
+// `src/visual-app/kind-icons.ts` and `badges.ts`, so this module can be
+// published standalone (`yarramate/notation/archimate`) and consumed by
+// non-canvas renderers. Not wired into `graph-canvas.tsx` yet (Task 4
+// switches the canvas to read from here instead of its own inline tables).
+import { conceptKinds, layers, relationshipKinds } from '../profile.js';
+export const ICON_SIZE = 14;
+const INK = '#182228'; // --ink (src/visual-app/styles.css:12)
+// The locked canvas layer palette (`graph-canvas.tsx`'s `LAYER_COLORS`
+// selectors) - `physical` and `composite` deliberately share the same
+// neutral grey since neither carries a distinct layer identity of its own.
+export const LAYER_COLORS = {
+    motivation: { fill: '#CCCCFF', border: '#8F8FE0' },
+    strategy: { fill: '#F5DEAA', border: '#C9A355' },
+    business: { fill: '#FFFF99', border: '#C9C355' },
+    application: { fill: '#CCFFFF', border: '#4FB8B8' },
+    technology: { fill: '#CCFFCC', border: '#5FAE5F' },
+    implementation: { fill: '#FFE0E0', border: '#D89999' },
+    physical: { fill: '#F0F0F0', border: '#999999' },
+    composite: { fill: '#F0F0F0', border: '#999999' },
+};
+// Aspect -> shape/accent/borderStyle, mirroring `graph-canvas.tsx`'s
+// `node[aspect = "…"]` selectors (Task 8/11 ArchiMate notation mode).
+export const ASPECT_SHAPES = {
+    motivation: { shape: 'octagon' },
+    'active-structure': { shape: 'rectangle' },
+    behavior: { shape: 'round-rectangle' },
+    'passive-structure': { shape: 'rectangle', accent: 'top-band' },
+    composite: { shape: 'rectangle', borderStyle: 'dashed' },
+};
+function svg(body) {
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${ICON_SIZE}" height="${ICON_SIZE}" ` +
+        `viewBox="0 0 ${ICON_SIZE} ${ICON_SIZE}">` +
+        `<g fill="none" stroke="${INK}" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">${body}</g>` +
+        `</svg>`);
+}
+function toDataUri(svgMarkup) {
+    return `data:image/svg+xml;utf8,${encodeURIComponent(svgMarkup)}`;
+}
+// The 17 kinds the canvas already draws a glyph for (`src/visual-app/
+// kind-icons.ts` `BASE_KIND_SVG`), copied verbatim. Every other core kind
+// (e.g. `stakeholder`) has no glyph body and resolves to `null` below -
+// that's an allowed gap, not a coverage failure: `CONCEPT_NOTATION` still
+// carries a row for it, just with `glyph: null`.
+const BASE_KIND_SVG = {
+    // Component: UML/ArchiMate component box with two connector notches on
+    // its left edge.
+    applicationComponent: '<rect x="3" y="2" width="9" height="10"/>' +
+        '<rect x="1" y="4" width="2.5" height="1.5"/>' +
+        '<rect x="1" y="8" width="2.5" height="1.5"/>',
+    // Function: rounded process box with a right-pointing chevron.
+    applicationFunction: '<rect x="2" y="3" width="10" height="8" rx="2"/><path d="M5.5 5 L8 7 L5.5 9"/>',
+    // Service: a pill/oval, ArchiMate's rounded-rectangle service shape.
+    applicationService: '<rect x="1.5" y="4" width="11" height="6" rx="3"/>',
+    // Artifact: a document with a folded top-right corner.
+    artifact: '<path d="M3 1.5 H9 L11 3.5 V12.5 H3 Z"/><path d="M9 1.5 V3.5 H11"/>',
+    // Actor: a stick figure - head, torso, arms, legs.
+    businessActor: '<circle cx="7" cy="3.5" r="1.8"/><path d="M7 5.3 V9 M4 7 H10 M7 9 L4.5 12.5 M7 9 L9.5 12.5"/>',
+    // Function: same process-box convention as applicationFunction, an
+    // upward chevron distinguishes the business layer.
+    businessFunction: '<rect x="2" y="3" width="10" height="8" rx="2"/><path d="M5 8 L7 5.5 L9 8"/>',
+    // Capability: a box with a compass-style arrow toward its top-right
+    // corner (capability-as-direction motif).
+    capability: '<rect x="2" y="2" width="10" height="10" rx="1"/><path d="M5 9 L9 5 M9 5 H6.5 M9 5 V7.5"/>',
+    // Data object: a record box with a header divider.
+    dataObject: '<rect x="2" y="2" width="10" height="10"/><path d="M2 5.5 H12"/>',
+    // Deliverable: a folded-corner document (like artifact) with a ribbon
+    // check-mark distinguishing it as a completed output.
+    deliverable: '<path d="M3 1.5 H8 L11 4.5 V12.5 H3 Z"/><path d="M8 1.5 V4.5 H11"/><path d="M5 9.5 L7 12.5 L9 9.5"/>',
+    // Driver: a steering-wheel motif - a circle with four radiating spokes.
+    driver: '<circle cx="7" cy="7" r="5"/><path d="M7 2 V5 M7 9 V12 M2 7 H5 M9 7 H12"/>',
+    // Goal: a target - two concentric circles.
+    goal: '<circle cx="7" cy="7" r="5"/><circle cx="7" cy="7" r="2.2"/>',
+    // Node: a 3D cuboid, ArchiMate's technology-node glyph.
+    node: '<path d="M2 5 L7 2.5 L12 5 L12 10 L7 12.5 L2 10 Z"/><path d="M2 5 L7 7.5 L12 5 M7 7.5 V12.5"/>',
+    // Plateau: a flat-topped trapezoid.
+    plateau: '<path d="M2 11 L4.5 4 H9.5 L12 11 Z"/><path d="M2 11 H12"/>',
+    // Representation: a document with a wavy bottom edge (curled paper).
+    representation: '<path d="M3 2 H11 V9 Q9.5 11 8 9.5 Q6.5 8 5 9.5 Q3.5 11 3 9 Z"/>',
+    // Requirement: a pointed banner/shield shape with a header divider.
+    requirement: '<path d="M3 2.5 H11 V9 L7 11.5 L3 9 Z"/><path d="M3 5 H11"/>',
+    // System software: a nested box, a smaller box docked inside the larger.
+    systemSoftware: '<rect x="2" y="2" width="10" height="10"/><rect x="4" y="4" width="4" height="3"/>',
+    // Function: same process convention again, technology layer gets a gear
+    // motif - a circle with radiating teeth.
+    technologyFunction: '<circle cx="7" cy="7" r="4"/>' +
+        '<path d="M7 2 V3.2 M7 10.8 V12 M2 7 H3.2 M10.8 7 H12 ' +
+        'M3.5 3.5 L4.3 4.3 M9.7 9.7 L10.5 10.5 M3.5 10.5 L4.3 9.7 M9.7 4.3 L10.5 3.5"/>',
+};
+// Built from `conceptKinds` (not enumerated by hand) so coverage cannot
+// drift from the core vocabulary - a new kind added to `profile.ts` gets a
+// notation row automatically, and a removed one disappears automatically.
+export const CONCEPT_NOTATION = conceptKinds.map((kind) => ({
+    id: kind.id,
+    notation: kind.name,
+    layer: kind.layer,
+    aspect: kind.aspect,
+    ...ASPECT_SHAPES[kind.aspect],
+    glyph: BASE_KIND_SVG[kind.id] ?? null,
+    colors: LAYER_COLORS[kind.layer],
+}));
+const CONCEPT_NOTATION_BY_ID = Object.fromEntries(CONCEPT_NOTATION.map((row) => [row.id, row]));
+export function conceptNotationOf(kindLabel) {
+    return CONCEPT_NOTATION_BY_ID[kindLabel] ?? null;
+}
+export function kindGlyphDataUriOf(kindLabel) {
+    const glyph = CONCEPT_NOTATION_BY_ID[kindLabel]?.glyph;
+    return glyph == null ? null : toDataUri(svg(glyph));
+}
+// The 11 rows from `graph-canvas.tsx`'s ArchiMate edge selectors (Task 11).
+const RELATIONSHIP_STYLE = {
+    composition: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'diamond', fill: 'filled' },
+        targetArrow: { shape: 'none' },
+    },
+    aggregation: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'diamond', fill: 'hollow' },
+        targetArrow: { shape: 'none' },
+    },
+    assignment: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'circle', fill: 'filled' },
+        targetArrow: { shape: 'triangle', fill: 'filled' },
+    },
+    realization: {
+        lineStyle: 'dotted',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'triangle', fill: 'hollow' },
+    },
+    specialization: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'triangle', fill: 'hollow' },
+    },
+    serving: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'vee' },
+    },
+    access: {
+        lineStyle: 'dotted',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'vee' },
+    },
+    influence: {
+        lineStyle: 'dashed',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'vee' },
+    },
+    triggering: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'triangle', fill: 'filled' },
+    },
+    flow: {
+        lineStyle: 'dashed',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'triangle', fill: 'filled' },
+    },
+    association: {
+        lineStyle: 'solid',
+        sourceArrow: { shape: 'none' },
+        targetArrow: { shape: 'none' },
+    },
+};
+// Built from `relationshipKinds` so coverage cannot drift, same discipline
+// as `CONCEPT_NOTATION` above.
+export const RELATIONSHIP_NOTATION = relationshipKinds.map((id) => ({
+    id,
+    ...RELATIONSHIP_STYLE[id],
+}));
+const RELATIONSHIP_NOTATION_BY_ID = Object.fromEntries(RELATIONSHIP_NOTATION.map((row) => [row.id, row]));
+export function relationshipNotationOf(kindLabel) {
+    return RELATIONSHIP_NOTATION_BY_ID[kindLabel] ?? null;
+}
+// `layers` is re-exported so consumers of this subpath don't need a second
+// import from `../profile.js` just to iterate the palette.
+export { layers };

package/dist/operations.d.ts

@@ -103,6 +103,22 @@ export type YarramateOperation = {
     readonly relationship: {
         readonly id: string;
     };
+} | {
+    readonly op: 'rename-concept';
+    readonly document: string;
+    readonly concept: {
+        readonly id: string;
+    };
+    /** The local id this subject should have had. Every declarative
+     * reference to the old address moves with it; prose does not. */
+    readonly to: string;
+} | {
+    readonly op: 'rename-relationship';
+    readonly document: string;
+    readonly relationship: {
+        readonly id: string;
+    };
+    readonly to: string;
 } | {
     readonly op: 'add-observation';
     readonly document: string;
@@ -131,6 +147,8 @@ export interface YarramateApplyResult {
         readonly updatedRelationships: number;
         readonly deletedConcepts: number;
         readonly deletedRelationships: number;
+        readonly renamedConcepts: number;
+        readonly renamedRelationships: number;
         readonly addedObservations: number;
         readonly updatedObservations: number;
         readonly deletedObservations: number;

package/dist/subject-references.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Every place a subject address can appear on disk, and the surgery that moves
+ * one. A rename is only honest if it is total: an address left behind is a
+ * dangling reference or, worse, a selector that silently stops matching. The
+ * enumeration below is the single statement of where those addresses live, and
+ * `test/subject-references.test.ts` derives the same set from the JSON Schemas
+ * so a new reference field cannot be added without landing here too.
+ */
+/** The four on-disk document kinds that can name a subject. */
+export type SubjectReferenceGroup = 'document' | 'projection' | 'evidence' | 'adapter-mapping';
+/**
+ * How the address is spelled at a position.
+ * - `declaration`: the subject's own local id, always bare, in its own document.
+ * - `reference`: bare local id (meaning "this document") or fully qualified.
+ * - `qualified`: always `document#local`, optionally with a `~aspect` suffix
+ *   (claim addresses are minted that way - see `compiler.ts`).
+ */
+export type SubjectReferenceForm = 'declaration' | 'reference' | 'qualified';
+export interface SubjectReferencePosition {
+    readonly group: SubjectReferenceGroup;
+    /** Key path from the document root; `*` matches every sequence index. */
+    readonly path: readonly string[];
+    readonly form: SubjectReferenceForm;
+}
+export declare const SUBJECT_REFERENCE_POSITIONS: readonly SubjectReferencePosition[];
+/**
+ * Positions that carry reference *syntax* but are not subject addresses, with
+ * the reason. Kept as data because the schema-derived completeness test asserts
+ * that the two lists together account for every reference-typed position: an
+ * omission has to be argued for here rather than forgotten.
+ */
+export declare const EXCLUDED_REFERENCE_POSITIONS: readonly {
+    readonly group: SubjectReferenceGroup;
+    readonly path: readonly string[];
+    readonly reason: string;
+}[];
+export interface SubjectReferenceHit {
+    /** JSON pointer into the document, for diagnostics. */
+    readonly pointer: string;
+    /** Qualified address with any `~aspect` suffix removed. */
+    readonly address: string;
+    readonly form: SubjectReferenceForm;
+    /** Source offsets of the scalar's own bytes, quotes included. */
+    readonly start: number;
+    readonly end: number;
+    /** The scalar exactly as written, quotes included. */
+    readonly raw: string;
+}
+export interface SubjectReferenceScan {
+    /** The document's own id, `''` when it declares none. */
+    readonly documentId: string;
+    readonly hits: readonly SubjectReferenceHit[];
+    /**
+     * Pointers at reference positions that hold an alias node. The walker cannot
+     * re-point one, so a rename refuses rather than silently leaving it behind.
+     */
+    readonly aliases: readonly string[];
+}
+/**
+ * Every subject address a file of this group holds. Pure read: the parse is
+ * thrown away, so callers stay free to splice the original bytes.
+ */
+export declare const scanSubjectReferences: (source: string, group: SubjectReferenceGroup) => SubjectReferenceScan;
+export interface SubjectRename {
+    /** Qualified address as declared today. */
+    readonly from: string;
+    /** Qualified address it should have had; the document part never moves. */
+    readonly to: string;
+}
+export type SubjectRewriteResult = {
+    readonly ok: true;
+    readonly source: string;
+    /** Pointers this rewrite moved, in document order. */
+    readonly moved: readonly string[];
+} | {
+    readonly ok: false;
+    readonly aliases: readonly string[];
+};
+/**
+ * Re-points every reference to `rename.from` in one file. Only the matched
+ * scalars' own bytes change - nothing is re-rendered, so byte identity holds
+ * everywhere else, a bare reference stays bare, a qualified one stays
+ * qualified, a `~aspect` suffix survives, and the original quoting is kept.
+ */
+export declare const rewriteSubjectReferences: (source: string, group: SubjectReferenceGroup, rename: SubjectRename) => SubjectRewriteResult;
+/**
+ * Local ids of the architecture states a document declares. States share the
+ * `document#local` spelling with subjects but not the id space, so a rename
+ * whose old or new id collides with one cannot be re-pointed unambiguously and
+ * is refused instead.
+ */
+export declare const declaredStateIds: (source: string) => readonly string[];

package/dist/subject-references.js

@@ -0,0 +1,226 @@
+import { isAlias, isMap, isScalar, isSeq, parseDocument } from 'yaml';
+export const SUBJECT_REFERENCE_POSITIONS = [
+    { group: 'document', path: ['concepts', '*', 'id'], form: 'declaration' },
+    { group: 'document', path: ['concepts', '*', 'owner'], form: 'reference' },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'distinctFrom', '*'],
+        form: 'reference',
+    },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'supersedes', '*'],
+        form: 'reference',
+    },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'constraints', '*', 'ref'],
+        form: 'reference',
+    },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'references', '*', 'ref'],
+        form: 'reference',
+    },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'attestations', '*', 'by'],
+        form: 'reference',
+    },
+    {
+        group: 'document',
+        path: ['relationships', '*', 'id'],
+        form: 'declaration',
+    },
+    {
+        group: 'document',
+        path: ['relationships', '*', 'from'],
+        form: 'reference',
+    },
+    { group: 'document', path: ['relationships', '*', 'to'], form: 'reference' },
+    {
+        group: 'document',
+        path: ['relationships', '*', 'references', '*', 'ref'],
+        form: 'reference',
+    },
+    {
+        group: 'projection',
+        path: ['query', 'subjects', '*'],
+        form: 'qualified',
+    },
+    { group: 'projection', path: ['query', 'owners', '*'], form: 'qualified' },
+    {
+        group: 'projection',
+        path: ['query', 'constraints', '*'],
+        form: 'qualified',
+    },
+    {
+        group: 'evidence',
+        path: ['observations', '*', 'subject'],
+        form: 'qualified',
+    },
+    {
+        group: 'evidence',
+        path: ['observations', '*', 'claim'],
+        form: 'qualified',
+    },
+    {
+        group: 'adapter-mapping',
+        path: ['mappings', '*', 'native'],
+        form: 'qualified',
+    },
+];
+/**
+ * Positions that carry reference *syntax* but are not subject addresses, with
+ * the reason. Kept as data because the schema-derived completeness test asserts
+ * that the two lists together account for every reference-typed position: an
+ * omission has to be argued for here rather than forgotten.
+ */
+export const EXCLUDED_REFERENCE_POSITIONS = [
+    {
+        group: 'document',
+        path: ['states', '*', 'after'],
+        reason: 'architecture state address, a separate id space',
+    },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'presentIn', '*'],
+        reason: 'architecture state address, a separate id space',
+    },
+    {
+        group: 'document',
+        path: ['relationships', '*', 'presentIn', '*'],
+        reason: 'architecture state address, a separate id space',
+    },
+    {
+        group: 'projection',
+        path: ['query', 'states', '*'],
+        reason: 'architecture state address, a separate id space',
+    },
+    {
+        group: 'document',
+        path: ['concepts', '*', 'constraints', '*', 'expects', 'key'],
+        reason: 'observation key: provider vocabulary, not an address',
+    },
+    {
+        group: 'evidence',
+        path: ['observations', '*', 'key'],
+        reason: 'observation key: provider vocabulary, not an address',
+    },
+];
+const qualify = (documentId, value) => value.includes('#') ? value : `${documentId}#${value}`;
+const localOf = (qualified) => qualified.slice(qualified.indexOf('#') + 1);
+/** Walks one position pattern and collects what it reaches. */
+const collect = (node, path, pointer, form, documentId, source, hits, aliases) => {
+    if (path.length === 0) {
+        if (isAlias(node)) {
+            aliases.push(pointer);
+            return;
+        }
+        if (!isScalar(node) || typeof node.value !== 'string')
+            return;
+        const range = node.range;
+        if (range === null || range === undefined)
+            return;
+        const [start, end] = range;
+        const aspect = node.value.indexOf('~');
+        const base = aspect === -1 ? node.value : node.value.slice(0, aspect);
+        hits.push({
+            pointer,
+            address: form === 'qualified' ? base : qualify(documentId, base),
+            form,
+            start,
+            end,
+            raw: source.slice(start, end),
+        });
+        return;
+    }
+    const [segment, ...rest] = path;
+    if (segment === '*') {
+        if (!isSeq(node))
+            return;
+        for (const [index, item] of node.items.entries()) {
+            collect(item, rest, `${pointer}/${index}`, form, documentId, source, hits, aliases);
+        }
+        return;
+    }
+    if (!isMap(node))
+        return;
+    collect(node.get(segment, true), rest, `${pointer}/${segment}`, form, documentId, source, hits, aliases);
+};
+/**
+ * Every subject address a file of this group holds. Pure read: the parse is
+ * thrown away, so callers stay free to splice the original bytes.
+ */
+export const scanSubjectReferences = (source, group) => {
+    const root = parseDocument(source).contents;
+    const id = isMap(root) ? root.get('id', true) : undefined;
+    const documentId = isScalar(id) && typeof id.value === 'string' ? id.value : '';
+    const hits = [];
+    const aliases = [];
+    for (const position of SUBJECT_REFERENCE_POSITIONS) {
+        if (position.group !== group)
+            continue;
+        collect(root, position.path, '', position.form, documentId, source, hits, aliases);
+    }
+    return { documentId, hits, aliases };
+};
+/** The quote character a scalar was written with, `''` when it was plain. */
+const quoteOf = (raw) => (raw.startsWith("'") && raw.endsWith("'")) ||
+    (raw.startsWith('"') && raw.endsWith('"'))
+    ? raw[0]
+    : '';
+/**
+ * Re-points every reference to `rename.from` in one file. Only the matched
+ * scalars' own bytes change - nothing is re-rendered, so byte identity holds
+ * everywhere else, a bare reference stays bare, a qualified one stays
+ * qualified, a `~aspect` suffix survives, and the original quoting is kept.
+ */
+export const rewriteSubjectReferences = (source, group, rename) => {
+    const scan = scanSubjectReferences(source, group);
+    if (scan.aliases.length > 0)
+        return { ok: false, aliases: scan.aliases };
+    const matches = scan.hits.filter((hit) => hit.address === rename.from);
+    if (matches.length === 0)
+        return { ok: true, source, moved: [] };
+    let rewritten = source;
+    // Back to front, so an earlier splice never shifts a later offset.
+    const ordered = [...matches].sort((left, right) => right.start - left.start);
+    for (const hit of ordered) {
+        const quote = quoteOf(hit.raw);
+        const written = quote === '' ? hit.raw : hit.raw.slice(1, -1);
+        const aspect = written.indexOf('~');
+        const suffix = aspect === -1 ? '' : written.slice(aspect);
+        const moved = written.includes('#') ? rename.to : localOf(rename.to);
+        rewritten =
+            rewritten.slice(0, hit.start) +
+                `${quote}${moved}${suffix}${quote}` +
+                rewritten.slice(hit.end);
+    }
+    return {
+        ok: true,
+        source: rewritten,
+        moved: matches.map((hit) => hit.pointer),
+    };
+};
+/**
+ * Local ids of the architecture states a document declares. States share the
+ * `document#local` spelling with subjects but not the id space, so a rename
+ * whose old or new id collides with one cannot be re-pointed unambiguously and
+ * is refused instead.
+ */
+export const declaredStateIds = (source) => {
+    const root = parseDocument(source).contents;
+    const states = isMap(root) ? root.get('states', true) : undefined;
+    if (!isSeq(states))
+        return [];
+    const ids = [];
+    for (const item of states.items) {
+        if (!isMap(item))
+            continue;
+        const id = item.get('id', true);
+        if (isScalar(id) && typeof id.value === 'string')
+            ids.push(id.value);
+    }
+    return ids;
+};