yarramate 0.18.0 → 0.20.0

package/dist/graph-projection.js

@@ -0,0 +1,222 @@
+import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, parseConstraintExpectsValue, } from './compiler.js';
+import { kindLabelOf } from './kind-label.js';
+const CONCEPT_KIND_PREDICATE = 'yarramate/concept/kind';
+const CONCEPT_NAME_PREDICATE = 'yarramate/concept/name';
+const CONCEPT_DESCRIPTION_PREDICATE = 'yarramate/concept/description';
+const CONCEPT_ALIAS_PREDICATE = 'yarramate/concept/alias';
+const LIFECYCLE_STATUS_PREDICATE = 'yarramate/lifecycle/status';
+const IDENTITY_DISTINCT_FROM_PREDICATE = 'yarramate/identity/distinct-from';
+const LINEAGE_SUPERSEDES_PREDICATE = 'yarramate/lineage/supersedes';
+const OWNERSHIP_OWNER_PREDICATE = 'yarramate/ownership/owner';
+const CONSTRAINT_REQUIRES_PREDICATE = 'yarramate/constraint/requires';
+const REFERENCE_REFERS_TO_PREDICATE = 'yarramate/reference/refers-to';
+const STATE_PRESENT_IN_PREDICATE = 'yarramate/state/present-in';
+const RELATIONSHIP_NAME_PREDICATE = 'yarramate/relationship/name';
+const RELATIONSHIP_DESCRIPTION_PREDICATE = 'yarramate/relationship/description';
+const ACCESS_MODE_PREDICATE = 'yarramate/access/mode';
+const FLOW_CONTENT_PREDICATE = 'yarramate/flow/content';
+// This is compiler-internal data: every claim's object narrows deterministically
+// by predicate. A mismatch means a real bug upstream in src/compiler.ts, not
+// malformed input this function should tolerate — so it throws rather than
+// silently coercing to an empty string.
+const claimValue = (claim) => {
+    if ('value' in claim.object) {
+        return claim.object.value;
+    }
+    throw new Error(`Expected a value-typed object for claim "${claim.id}" (subject "${claim.subject}", predicate "${claim.predicate}"), got a ref-typed object`);
+};
+const claimRef = (claim) => {
+    if ('ref' in claim.object) {
+        return claim.object.ref;
+    }
+    throw new Error(`Expected a ref-typed object for claim "${claim.id}" (subject "${claim.subject}", predicate "${claim.predicate}"), got a value-typed object`);
+};
+// The compiler qualifies every subject id as `<document id>#<authored id>`
+// (`qualifyReference` in src/compiler.ts), and a document's authored ids never
+// contain `#`. An operation addresses a subject by the id someone wrote in the
+// file, not by the qualified identity the compile derived, so the projection
+// carries both rather than leaving the browser to re-derive one from the other.
+const authoredIdOf = (subjectId) => {
+    const boundary = subjectId.indexOf('#');
+    return boundary === -1 ? subjectId : subjectId.slice(boundary + 1);
+};
+const compareById = (left, right) => left.id.localeCompare(right.id);
+const groupClaimsBySubject = (claims) => {
+    const groups = new Map();
+    for (const claim of claims) {
+        const group = groups.get(claim.subject);
+        if (group === undefined) {
+            groups.set(claim.subject, [claim]);
+        }
+        else {
+            group.push(claim);
+        }
+    }
+    return groups;
+};
+const projectConcept = (subjectId, claims, profileContext) => {
+    const kindClaim = claims.find((claim) => claim.predicate === CONCEPT_KIND_PREDICATE);
+    if (kindClaim === undefined) {
+        throw new Error(`Concept "${subjectId}" is missing its required yarramate/concept/kind claim`);
+    }
+    const kind = claimValue(kindClaim);
+    const nameClaim = claims.find((claim) => claim.predicate === CONCEPT_NAME_PREDICATE);
+    if (nameClaim === undefined) {
+        throw new Error(`Concept "${subjectId}" is missing its required yarramate/concept/name claim`);
+    }
+    const descriptionClaim = claims.find((claim) => claim.predicate === CONCEPT_DESCRIPTION_PREDICATE);
+    const statusClaim = claims.find((claim) => claim.predicate === LIFECYCLE_STATUS_PREDICATE);
+    const ownerClaim = claims.find((claim) => claim.predicate === OWNERSHIP_OWNER_PREDICATE);
+    const constraints = claims
+        .filter((claim) => claim.predicate === CONSTRAINT_REQUIRES_PREDICATE)
+        .map((requiresClaim) => {
+        // The constraint's local id lives between the `~constraint-` marker
+        // and the end of the requires claim's own id; the paired expects
+        // claim (if the constraint declared one) reuses that same local id
+        // under a `~expects-` marker in the same claim group.
+        const localId = requiresClaim.id.split('~constraint-')[1];
+        if (localId === undefined) {
+            throw new Error(`Constraint claim "${requiresClaim.id}" on concept "${subjectId}" does not follow the "<subject>~constraint-<id>" id convention`);
+        }
+        const expectsClaim = claims.find((claim) => claim.id === `${subjectId}~expects-${localId}`);
+        let expects;
+        if (expectsClaim === undefined) {
+            expects = null;
+        }
+        else {
+            const parsed = parseConstraintExpectsValue(claimValue(expectsClaim));
+            if (parsed === undefined) {
+                throw new Error(`Constraint expects claim "${expectsClaim.id}" on concept "${subjectId}" does not follow the "provider key value" encoding`);
+            }
+            expects = parsed;
+        }
+        return {
+            id: localId,
+            ref: claimRef(requiresClaim),
+            expects,
+        };
+    });
+    const attestations = claims
+        .filter((claim) => claim.predicate.startsWith(ATTESTATION_PREDICATE_PREFIX))
+        .map((claim) => {
+        const parsed = parseAttestationClaimValue(claimValue(claim));
+        if (parsed === undefined) {
+            throw new Error(`Attestation claim "${claim.id}" on concept "${subjectId}" does not follow the "by on [recordedBy]" encoding`);
+        }
+        return {
+            topic: claim.predicate.slice(ATTESTATION_PREDICATE_PREFIX.length),
+            by: parsed.by,
+            on: parsed.on,
+            recordedBy: parsed.recordedBy ?? null,
+        };
+    });
+    return {
+        id: subjectId,
+        localId: authoredIdOf(subjectId),
+        document: kindClaim.source.path,
+        kind,
+        kindLabel: kindLabelOf(kind),
+        layer: profileContext.conceptKindLayers.get(kind) ?? null,
+        aspect: profileContext.conceptKindAspects.get(kind) ?? null,
+        name: claimValue(nameClaim),
+        description: descriptionClaim === undefined ? null : claimValue(descriptionClaim),
+        aka: claims
+            .filter((claim) => claim.predicate === CONCEPT_ALIAS_PREDICATE)
+            .map(claimValue)
+            .sort(),
+        status: statusClaim === undefined ? null : claimValue(statusClaim),
+        owner: ownerClaim === undefined ? null : claimRef(ownerClaim),
+        distinctFrom: claims
+            .filter((claim) => claim.predicate === IDENTITY_DISTINCT_FROM_PREDICATE)
+            .map(claimRef)
+            .sort(),
+        supersedes: claims
+            .filter((claim) => claim.predicate === LINEAGE_SUPERSEDES_PREDICATE)
+            .map(claimRef)
+            .sort(),
+        constraints,
+        references: claims
+            .filter((claim) => claim.predicate === REFERENCE_REFERS_TO_PREDICATE)
+            .map((referencesClaim) => {
+            const localId = referencesClaim.id.split('~reference-')[1];
+            if (localId === undefined) {
+                throw new Error(`Reference claim "${referencesClaim.id}" on concept "${subjectId}" does not follow the "<subject>~reference-<id>" id convention`);
+            }
+            return {
+                id: localId,
+                ref: claimRef(referencesClaim),
+            };
+        })
+            .sort((left, right) => left.ref.localeCompare(right.ref)),
+        presentIn: claims
+            .filter((claim) => claim.predicate === STATE_PRESENT_IN_PREDICATE)
+            .map(claimRef)
+            .sort(),
+        attestations,
+    };
+};
+const projectRelationship = (relationshipId, allClaims, ownClaims, profileContext) => {
+    // A relationship's defining claim is asymmetric: its id is the
+    // relationship's subject id, but its own `subject` field is the
+    // from-concept, so it lives in the from-concept's claim group, not this
+    // relationship's — it has to be found by scanning every claim.
+    const definingClaim = allClaims.find((claim) => claim.id === relationshipId);
+    if (definingClaim === undefined) {
+        throw new Error(`Relationship "${relationshipId}" is missing its defining claim`);
+    }
+    const kind = definingClaim.predicate;
+    const nameClaim = ownClaims.find((claim) => claim.predicate === RELATIONSHIP_NAME_PREDICATE);
+    const descriptionClaim = ownClaims.find((claim) => claim.predicate === RELATIONSHIP_DESCRIPTION_PREDICATE);
+    const modeClaim = ownClaims.find((claim) => claim.predicate === ACCESS_MODE_PREDICATE);
+    const contentClaim = ownClaims.find((claim) => claim.predicate === FLOW_CONTENT_PREDICATE);
+    const statusClaim = ownClaims.find((claim) => claim.predicate === LIFECYCLE_STATUS_PREDICATE);
+    return {
+        id: relationshipId,
+        localId: authoredIdOf(relationshipId),
+        document: definingClaim.source.path,
+        kind,
+        kindLabel: kindLabelOf(kind),
+        coreKindLabel: kindLabelOf(profileContext.relationshipKindLineages.get(kind)?.[0] ?? kind),
+        from: definingClaim.subject,
+        to: claimRef(definingClaim),
+        name: nameClaim === undefined ? null : claimValue(nameClaim),
+        description: descriptionClaim === undefined ? null : claimValue(descriptionClaim),
+        mode: modeClaim === undefined ? null : claimValue(modeClaim),
+        content: contentClaim === undefined ? null : claimValue(contentClaim),
+        status: statusClaim === undefined ? null : claimValue(statusClaim),
+        references: ownClaims
+            .filter((claim) => claim.predicate === REFERENCE_REFERS_TO_PREDICATE)
+            .map((referencesClaim) => {
+            const localId = referencesClaim.id.split('~reference-')[1];
+            if (localId === undefined) {
+                throw new Error(`Reference claim "${referencesClaim.id}" on relationship "${relationshipId}" does not follow the "<subject>~reference-<id>" id convention`);
+            }
+            return {
+                id: localId,
+                ref: claimRef(referencesClaim),
+            };
+        })
+            .sort((left, right) => left.ref.localeCompare(right.ref)),
+        presentIn: ownClaims
+            .filter((claim) => claim.predicate === STATE_PRESENT_IN_PREDICATE)
+            .map(claimRef)
+            .sort(),
+    };
+};
+export function projectGraphForCanvas(graph, profileContext) {
+    const claimsBySubject = groupClaimsBySubject(graph.claims);
+    const nodes = [];
+    const edges = [];
+    for (const subject of graph.subjects) {
+        const ownClaims = claimsBySubject.get(subject.id) ?? [];
+        if (subject.type === 'concept') {
+            nodes.push(projectConcept(subject.id, ownClaims, profileContext));
+        }
+        else {
+            edges.push(projectRelationship(subject.id, graph.claims, ownClaims, profileContext));
+        }
+    }
+    nodes.sort(compareById);
+    edges.sort(compareById);
+    return { nodes, edges };
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
+export { compileWorkspace, compileWorkspaceIncremental, compileWorkspaceWithProfileContext, } from './compiler.js';
 export { serializeSemanticGraph } from './graph.js';
 export { checkCoreContract, loadCoreContract, type CoreContract, type CoreContractCommand, type CoreContractFormat, type CoreContractLoadResult, type CoreContractSurface, } from './core-contract.js';
 export { compareArchitectureStates, type StateComparison, type StateComparisonIssue, type StateComparisonResult, } from './architecture-state.js';
@@ -7,7 +7,7 @@ export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, type Evidenc
 export { constraintExpectsPredicate, reconcileEvidenceReports, type AssertedRelationship, type AttestationStaleness, type DeclaredSource, type EvidenceFinding, type ExpectationComparison, type ReconciliationFinding, type ReconciliationReport, type StaleAttestationFinding, type UnobservedExpectation, } from './reconciliation.js';
 export { deriveAttestationStaleness } from './attestation-staleness.js';
 export { buildRtm, renderRtmMarkdown, type RequirementsTraceabilityMatrix, type RtmAttestation, type RtmContextEntry, type RtmDescopedEntry, type RtmEvidenceVerdict, type RtmLineageEntry, type RtmRealizer, type RtmRow, type RtmSource, } from './rtm.js';
-export type { CompilationResult, ContextualCompilationResult, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
+export type { CompilationCache, CompilationResult, ContextualCompilationResult, IncrementalCompilationResult, ParsedWorkspaceSource, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
 export { canonicalProjection, evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, type AdapterMapping, type AdapterMappingLoadResult, type AdapterMappingValidationResult, type AdapterMappingsValidationResult, type AdapterSubjectMapping, } from './adapter-mapping.js';
 export type { LifecycleStatus, ProjectionDefinition, ProjectionLoadResult, ProjectionResult, } from './projection.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
+export { compileWorkspace, compileWorkspaceIncremental, compileWorkspaceWithProfileContext, } from './compiler.js';
 export { serializeSemanticGraph } from './graph.js';
 export { checkCoreContract, loadCoreContract, } from './core-contract.js';
 export { compareArchitectureStates, } from './architecture-state.js';

package/dist/interrogate-command.d.ts

@@ -35,6 +35,8 @@ type CatalogueCondition = {
     readonly topic: string;
 } | {
     readonly condition: 'near-duplicate';
+} | {
+    readonly condition: 'unconstrained-kind';
 };
 export interface CatalogueQuestion {
     readonly id: string;

package/dist/interrogate-command.js

@@ -224,6 +224,28 @@ const conditionHolds = (index, condition, subjectId, profileContext) => {
             // index, so this reads exactly like every other condition: the claim's
             // existence is the whole signal (ADR 0056).
             return (index.nearDuplicates().get(subjectId) ?? []).length > 0;
+        case 'unconstrained-kind': {
+            // A compiled graph already satisfies every aspect rule it is subject to
+            // (YM404), so participation in a kind that pins the aspect at this
+            // subject's end is the whole test: reclassify the subject to another
+            // aspect and the workspace stops compiling. Where no such claim exists
+            // the kind is a label the engine can never contradict (ADR 0083).
+            // Without a profile context the rules are unknown, not absent, so the
+            // condition reports nothing rather than inventing a finding.
+            if (profileContext === undefined)
+                return false;
+            return !index.relationshipClaims.some((claim) => {
+                const endpoints = profileContext.relationshipKindEndpointAspects.get(claim.predicate);
+                if (endpoints === undefined)
+                    return false;
+                if (endpoints.source !== undefined && claim.subject === subjectId) {
+                    return true;
+                }
+                return (endpoints.target !== undefined &&
+                    'ref' in claim.object &&
+                    claim.object.ref === subjectId);
+            });
+        }
     }
 };
 // Shared with design: question templates (standard and askPlain alike)

package/dist/kind-label.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A kind identity is `<profile>#<local id>`, and its label is that local id.
+ *
+ * This lives apart from `graph-projection.ts` because the browser needs it:
+ * the projection imports the compiler, and the compiler reaches for Ajv
+ * through `node:module` at load, which a bundle cannot honour.
+ */
+export declare const kindLabelOf: (kind: string) => string;

package/dist/kind-label.js

@@ -0,0 +1,8 @@
+/**
+ * A kind identity is `<profile>#<local id>`, and its label is that local id.
+ *
+ * This lives apart from `graph-projection.ts` because the browser needs it:
+ * the projection imports the compiler, and the compiler reaches for Ajv
+ * through `node:module` at load, which a bundle cannot honour.
+ */
+export const kindLabelOf = (kind) => kind.slice(kind.lastIndexOf('#') + 1);

package/dist/operations.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The `yarramate/operations/v1` document shape, and the result of landing one.
+ *
+ * These declarations are the typed twin of `schema/yarramate-operations.schema.json`
+ * and `schema/yarramate-apply-result.schema.json`. They live apart from
+ * `./apply-command.js` - which owns the machinery that validates, splices, and
+ * writes a batch - because the visual protocol carries the same documents to a
+ * browser that must not pull Ajv, `yaml`, or `node:fs` into its bundle or its
+ * typecheck. Types only: this module has no runtime dependency of any kind.
+ */
+export interface IdentifiedReference {
+    readonly id: string;
+    readonly ref: string;
+}
+export interface ConstraintReference extends IdentifiedReference {
+    readonly expects?: {
+        readonly provider: string;
+        readonly key: string;
+        readonly value: string;
+    };
+}
+export interface ConceptFields {
+    readonly id: string;
+    readonly kind?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly aka?: readonly string[];
+    readonly status?: string;
+    readonly owner?: string;
+    readonly distinctFrom?: readonly string[];
+    readonly supersedes?: readonly string[];
+    readonly constraints?: readonly ConstraintReference[];
+    readonly references?: readonly IdentifiedReference[];
+    readonly presentIn?: readonly string[];
+    readonly attestations?: ReadonlyArray<{
+        readonly topic: string;
+        readonly by: string;
+        readonly recordedBy: string;
+        readonly on: string;
+    }>;
+}
+export interface RelationshipFields {
+    readonly id: string;
+    readonly kind?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly status?: string;
+    readonly mode?: string;
+    readonly content?: string;
+    readonly references?: readonly IdentifiedReference[];
+    readonly presentIn?: readonly string[];
+}
+export interface ObservationTarget {
+    readonly subject?: string;
+    readonly claim?: string;
+    readonly key?: string;
+}
+export interface ObservationFields extends ObservationTarget {
+    readonly value?: string;
+    readonly result?: 'confirmed' | 'contradicted' | 'unknown' | 'not-observed';
+    readonly evidence?: {
+        readonly uri: string;
+        readonly message?: string;
+    };
+}
+export interface ObservationChange extends ObservationTarget {
+    readonly value?: string;
+    readonly result?: 'confirmed' | 'contradicted' | 'unknown' | 'not-observed';
+    readonly evidence?: {
+        readonly uri?: string;
+        readonly message?: string;
+    };
+}
+export type YarramateOperation = {
+    readonly op: 'add-concept';
+    readonly document: string;
+    readonly concept: ConceptFields;
+} | {
+    readonly op: 'add-relationship';
+    readonly document: string;
+    readonly relationship: RelationshipFields;
+} | {
+    readonly op: 'update-concept';
+    readonly document: string;
+    readonly concept: ConceptFields;
+    readonly remove?: readonly string[];
+} | {
+    readonly op: 'update-relationship';
+    readonly document: string;
+    readonly relationship: RelationshipFields;
+    readonly remove?: readonly string[];
+} | {
+    readonly op: 'delete-concept';
+    readonly document: string;
+    readonly concept: {
+        readonly id: string;
+    };
+} | {
+    readonly op: 'delete-relationship';
+    readonly document: string;
+    readonly relationship: {
+        readonly id: string;
+    };
+} | {
+    readonly op: 'add-observation';
+    readonly document: string;
+    readonly observation: ObservationFields;
+} | {
+    readonly op: 'update-observation';
+    readonly document: string;
+    readonly observation: ObservationChange;
+    readonly remove?: readonly string[];
+} | {
+    readonly op: 'delete-observation';
+    readonly document: string;
+    readonly observation: ObservationTarget;
+};
+export interface OperationsDocument {
+    readonly format: 'yarramate/operations/v1';
+    readonly operations: readonly YarramateOperation[];
+}
+export interface YarramateApplyResult {
+    readonly format: 'yarramate/apply-result/v1';
+    readonly workspace: string;
+    readonly applied: {
+        readonly addedConcepts: number;
+        readonly addedRelationships: number;
+        readonly updatedConcepts: number;
+        readonly updatedRelationships: number;
+        readonly deletedConcepts: number;
+        readonly deletedRelationships: number;
+        readonly addedObservations: number;
+        readonly updatedObservations: number;
+        readonly deletedObservations: number;
+    };
+    readonly documents: readonly string[];
+}

package/dist/operations.js

@@ -0,0 +1,11 @@
+/**
+ * The `yarramate/operations/v1` document shape, and the result of landing one.
+ *
+ * These declarations are the typed twin of `schema/yarramate-operations.schema.json`
+ * and `schema/yarramate-apply-result.schema.json`. They live apart from
+ * `./apply-command.js` - which owns the machinery that validates, splices, and
+ * writes a batch - because the visual protocol carries the same documents to a
+ * browser that must not pull Ajv, `yaml`, or `node:fs` into its bundle or its
+ * typecheck. Types only: this module has no runtime dependency of any kind.
+ */
+export {};

package/dist/projection.d.ts

@@ -28,8 +28,10 @@ export interface ProjectionDefinition {
         readonly showLifecycle?: boolean;
         readonly showEvidence?: boolean;
         readonly showOwnership?: boolean;
+        readonly notation?: 'native' | 'archimate';
     };
 }
+export type ProjectionQuery = ProjectionDefinition['query'];
 export interface ProjectionResult {
     readonly format: 'yarramate/projection-result/v1';
     readonly projection: string;

package/dist/projection.js

@@ -1,9 +1,11 @@
-import Ajv2020Module from 'ajv/dist/2020.js';
+import { createRequire } from 'node:module';
 import { isDeclaredNonGoal } from './brief.js';
 import { loadSourceDocument } from './source-document.js';
 import projectionSchema from '../schema/yarramate-projection.schema.json' with { type: 'json'
 };
-const Ajv2020 = Ajv2020Module.default;
+const require = createRequire(import.meta.url);
+const ajv2020Module = require('ajv/dist/2020.js');
+const Ajv2020 = ajv2020Module.default ?? ajv2020Module;
 const validateProjection = new Ajv2020({ allErrors: true }).compile(projectionSchema);
 export function loadProjection(source) {
     const loaded = loadSourceDocument(source, validateProjection, 'Projection');
@@ -45,6 +47,7 @@ export function canonicalProjection(projection) {
                     ...(presentation.showLifecycle === undefined ? {} : { showLifecycle: presentation.showLifecycle }),
                     ...(presentation.showEvidence === undefined ? {} : { showEvidence: presentation.showEvidence }),
                     ...(presentation.showOwnership === undefined ? {} : { showOwnership: presentation.showOwnership }),
+                    ...(presentation.notation === undefined ? {} : { notation: presentation.notation }),
                 },
             }),
     };
@@ -226,6 +229,9 @@ export function evaluateProjection(graph, projection, profileContext) {
                     ...(projection.presentation.showOwnership === undefined
                         ? {}
                         : { showOwnership: projection.presentation.showOwnership }),
+                    ...(projection.presentation.notation === undefined
+                        ? {}
+                        : { notation: projection.presentation.notation }),
                 },
             }),
         documents: graph.documents.filter(({ id }) => selectedDocuments.has(id)),

package/dist/reconciliation.js

@@ -1,4 +1,4 @@
-import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, } from './compiler.js';
+import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, parseConstraintExpectsValue, } from './compiler.js';
 const assertedRelationshipsByClaim = (graph) => {
     const asserted = new Map();
     if (graph === undefined)
@@ -30,7 +30,8 @@ export const constraintExpectsPredicate = 'yarramate/constraint/expects';
 // A finding is now a union (ADR 0074); only the evidence arm can carry an
 // expectation, so ordering reads it through one narrowing helper.
 const expectationOf = (finding) => 'expectation' in finding ? finding.expectation : undefined;
-// Mirrors the compiler encoding (ADR 0075). Provider and key admit no
+// The compiler's parseConstraintExpectsValue is the sole authority for
+// decoding the encoded value (ADR 0075). Provider and key admit no
 // whitespace, so the first two spaces delimit them and everything after the
 // second space is the expected value verbatim, spaces included.
 const parseExpectation = (claim) => {
@@ -38,15 +39,15 @@ const parseExpectation = (claim) => {
         !('value' in claim.object)) {
         return undefined;
     }
-    const match = /^(\S+) (\S+) ([\s\S]+)$/.exec(claim.object.value);
-    if (match === null)
+    const parts = parseConstraintExpectsValue(claim.object.value);
+    if (parts === undefined)
         return undefined;
     return {
         claim: claim.id,
         subject: claim.subject,
-        provider: match[1],
-        key: match[2],
-        expected: match[3],
+        provider: parts.provider,
+        key: parts.key,
+        expected: parts.value,
         declared: {
             document: claim.source.document,
             path: claim.source.path,

package/dist/source-document.d.ts

@@ -21,6 +21,16 @@ export type SourceDocumentResult<T> = {
 };
 export declare const diagnosticOrder: (left: Diagnostic, right: Diagnostic) => number;
 export declare const describeSchemaViolation: (error: Pick<ErrorObject, 'keyword' | 'message' | 'params'>) => string;
+/**
+ * The errors worth reading, in the order Ajv found them.
+ *
+ * A discriminated union raises two errors when the tag itself is missing or
+ * mistyped: the `required`/`type` fault that names the property, and a
+ * `discriminator` row restating it. The second says nothing the first did not,
+ * so it is dropped. A tag that is present but names no branch keeps its row -
+ * that one is the only report of the fault.
+ */
+export declare const readableSchemaErrors: <T extends Pick<ErrorObject, 'keyword' | 'params'>>(errors: readonly T[]) => readonly T[];
 export declare const closestCandidate: (value: string, candidates: Iterable<string>) => string | undefined;
 export declare function locateSourcePath(sourcePath: string, yaml: ReturnType<typeof parseDocument>, lineCounter: LineCounter, yamlPath: readonly (string | number)[], pointer: string): SourceLocation;
 export declare function loadSourceDocument<T>(source: WorkspaceSource, validate: ValidateFunction, schemaLabel: string): SourceDocumentResult<T>;

package/dist/source-document.js

@@ -18,8 +18,28 @@ export const describeSchemaViolation = (error) => {
             .join(', ');
         return `${base}: ${shown}${allowed.length > 8 ? ', …' : ''}`;
     }
+    // The one pattern in these schemas that is a rule rather than a shape:
+    // `must match pattern "\S"` names the regex, not what the author did wrong.
+    if (error.keyword === 'pattern' && error.params.pattern === '\\S') {
+        return 'must not be blank';
+    }
+    // A tag naming no branch reads as a search failure ("must be in oneOf").
+    // Say what was named instead, since that is the value to correct.
+    if (error.keyword === 'discriminator' && error.params.error === 'mapping') {
+        return `unknown ${JSON.stringify(error.params.tag)} value ${JSON.stringify(error.params.tagValue)}`;
+    }
     return base;
 };
+/**
+ * The errors worth reading, in the order Ajv found them.
+ *
+ * A discriminated union raises two errors when the tag itself is missing or
+ * mistyped: the `required`/`type` fault that names the property, and a
+ * `discriminator` row restating it. The second says nothing the first did not,
+ * so it is dropped. A tag that is present but names no branch keeps its row -
+ * that one is the only report of the fault.
+ */
+export const readableSchemaErrors = (errors) => errors.filter((error) => error.keyword !== 'discriminator' || error.params.error === 'mapping');
 const editDistance = (left, right) => {
     const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
     for (let i = 1; i <= left.length; i += 1) {
@@ -86,7 +106,7 @@ export function loadSourceDocument(source, validate, schemaLabel) {
     if (!validate(value)) {
         return {
             ok: false,
-            diagnostics: (validate.errors ?? [])
+            diagnostics: readableSchemaErrors(validate.errors ?? [])
                 .map((error) => {
                 const property = error.keyword === 'additionalProperties'
                     ? String(error.params.additionalProperty)