yarramate 0.3.3 → 0.5.0

package/dist/compiler.js

@@ -1,6 +1,7 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { LineCounter, parseDocument } from 'yaml';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
+import { closestCandidate, describeSchemaViolation, } from './source-document.js';
 import documentSchema from '../schema/yarramate-document.schema.json' with {
     type: 'json'
 };
@@ -53,6 +54,7 @@ function compileWorkspaceResolved(sources) {
             lineage: [`${coreProfile}#${policy.id}`],
             sourceAspects: policy.sourceAspects,
             targetAspects: policy.targetAspects,
+            repair: policy.repair,
         };
         coreRelationshipKinds.set(policy.id, resolved);
         relationshipKindByIdentity.set(resolved.identity, resolved);
@@ -112,7 +114,7 @@ function compileWorkspaceResolved(sources) {
                     code: 'YM201',
                     message: property
                         ? `Property "${property}" is not allowed`
-                        : `Profile schema violation: ${error.message ?? error.keyword}`,
+                        : `Profile schema violation: ${describeSchemaViolation(error)}`,
                     path: input.path,
                     pointer,
                     line: position.line,
@@ -335,7 +337,7 @@ function compileWorkspaceResolved(sources) {
                         code: 'YM201',
                         message: property
                             ? `Property "${property}" is not allowed`
-                            : `Document schema violation: ${error.message ?? error.keyword}`,
+                            : `Document schema violation: ${describeSchemaViolation(error)}`,
                         path: input.path,
                         pointer,
                         line: source.line,
@@ -536,7 +538,12 @@ function compileWorkspaceResolved(sources) {
                 diagnostics.push({
                     severity: 'error',
                     code: 'YM401',
-                    message: `Unknown concept kind "${concept.kind}" in profile "${value.profile}"`,
+                    message: `Unknown concept kind "${concept.kind}" in profile "${value.profile}"${(() => {
+                        const suggestion = closestCandidate(concept.kind, selectedProfile.conceptKinds.keys());
+                        return suggestion === undefined
+                            ? ''
+                            : `; did you mean "${suggestion}"?`;
+                    })()}`,
                     path: input.path,
                     pointer,
                     line: source.line,
@@ -742,7 +749,12 @@ function compileWorkspaceResolved(sources) {
                 diagnostics.push({
                     severity: 'error',
                     code: 'YM402',
-                    message: `Unknown relationship kind "${relationship.kind}" in profile "${value.profile}"`,
+                    message: `Unknown relationship kind "${relationship.kind}" in profile "${value.profile}"${(() => {
+                        const suggestion = closestCandidate(relationship.kind, selectedProfile.relationshipKinds.keys());
+                        return suggestion === undefined
+                            ? ''
+                            : `; did you mean "${suggestion}"?`;
+                    })()}`,
                     path: input.path,
                     pointer,
                     line: source.line,
@@ -787,7 +799,7 @@ function compileWorkspaceResolved(sources) {
                         diagnostics.push({
                             severity: 'error',
                             code: 'YM404',
-                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((aspect) => `"${aspect}"`).join(' or ')}; "${reference}" has aspect "${kind.aspect}"`,
+                            message: `Relationship "${relationship.kind}" requires a ${endpoint} with aspect ${allowed.map((aspect) => `"${aspect}"`).join(' or ')}; "${reference}" has aspect "${kind.aspect}"${policy.repair === undefined ? '' : `; ${policy.repair}`}`,
                             path: input.path,
                             pointer,
                             line: source.line,

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { checkCoreContract, loadCoreContract, type CoreContract, type CoreContra
 export { compareArchitectureStates, type StateComparison, type StateComparisonIssue, type StateComparisonResult, } from './architecture-state.js';
 export { loadWorkspaceManifest, type ResolvedWorkspace, type WorkspaceManifest, type WorkspaceManifestResult, } from './workspace.js';
 export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, type EvidenceDocument, type EvidenceEvaluationResult, type EvidenceLoadResult, type EvidenceLocator, type EvidenceObservation, type EvidenceReport, type EvidenceResult, type EvidenceWorkspaceEvaluationResult, } from './evidence.js';
-export { reconcileEvidenceReports, type ReconciliationFinding, type ReconciliationReport, } from './reconciliation.js';
+export { reconcileEvidenceReports, type AssertedRelationship, type ReconciliationFinding, type ReconciliationReport, } from './reconciliation.js';
 export type { CompilationResult, ContextualCompilationResult, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
 export { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, type AdapterMapping, type AdapterMappingLoadResult, type AdapterMappingValidationResult, type AdapterMappingsValidationResult, type AdapterSubjectMapping, } from './adapter-mapping.js';

package/dist/new-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runNewCommand(options: readonly string[], cwd: string): CliResult;

package/dist/new-command.js

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { humanDiagnostics, usage } from './cli-support.js';
+import { loadProjection } from './projection.js';
+const singleValueFlags = new Set([
+    '--id',
+    '--version',
+    '--title',
+    '--description',
+    '--relationships',
+]);
+const repeatableFlags = new Set(['--document', '--subject', '--kind']);
+const yamlText = (value) => /^[A-Za-z0-9][A-Za-z0-9 ._/@#-]*$/.test(value)
+    ? value
+    : JSON.stringify(value);
+export function runNewCommand(options, cwd) {
+    const [family, target, ...flags] = options;
+    if (family !== 'projection' || target === undefined || target.startsWith('-')) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const single = new Map();
+    const repeated = new Map();
+    for (let index = 0; index < flags.length; index += 2) {
+        const flag = flags[index];
+        const value = flags[index + 1];
+        if (flag === undefined ||
+            value === undefined ||
+            value.startsWith('--') ||
+            (!singleValueFlags.has(flag) && !repeatableFlags.has(flag))) {
+            return { exitCode: 2, stdout: '', stderr: usage };
+        }
+        if (singleValueFlags.has(flag)) {
+            if (single.has(flag)) {
+                return { exitCode: 2, stdout: '', stderr: usage };
+            }
+            single.set(flag, value);
+        }
+        else {
+            repeated.set(flag, [...(repeated.get(flag) ?? []), value]);
+        }
+    }
+    const id = single.get('--id');
+    if (id === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const documents = repeated.get('--document');
+    const subjects = repeated.get('--subject');
+    const kinds = repeated.get('--kind');
+    if (documents === undefined && subjects === undefined && kinds === undefined) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: 'new projection requires at least one selector: --document, --subject, or --kind\n',
+        };
+    }
+    const targetPath = resolve(cwd, target);
+    if (existsSync(targetPath)) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: `${target} already exists; nothing was changed\n`,
+        };
+    }
+    const lines = [
+        'format: yarramate/projection/v1',
+        `id: ${yamlText(id)}`,
+        `version: "${single.get('--version') ?? '1.0'}"`,
+        'query:',
+    ];
+    const list = (key, values) => {
+        if (values === undefined)
+            return;
+        lines.push(`  ${key}:`);
+        for (const value of values)
+            lines.push(`    - ${yamlText(value)}`);
+    };
+    list('subjects', subjects);
+    list('documents', documents);
+    list('kinds', kinds);
+    const relationships = single.get('--relationships');
+    if (relationships !== undefined) {
+        lines.push(`  relationships: ${yamlText(relationships)}`);
+    }
+    const title = single.get('--title');
+    const description = single.get('--description');
+    if (title !== undefined || description !== undefined) {
+        lines.push('presentation:');
+        if (title !== undefined)
+            lines.push(`  title: ${yamlText(title)}`);
+        if (description !== undefined) {
+            lines.push(`  description: ${yamlText(description)}`);
+        }
+    }
+    const source = `${lines.join('\n')}\n`;
+    const loaded = loadProjection({ path: target, source });
+    if (!loaded.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(loaded.diagnostics),
+        };
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, source, 'utf8');
+    return {
+        exitCode: 0,
+        stdout: `Created ${target} (${loaded.projection.id}@${loaded.projection.version})\n` +
+            'Include it in the workspace manifest projections list if no glob already covers it\n',
+        stderr: '',
+    };
+}

package/dist/profile.d.ts

@@ -21,6 +21,11 @@ export interface RelationshipPolicy {
     readonly intent: string;
     readonly sourceAspects?: readonly Aspect[];
     readonly targetAspects?: readonly Aspect[];
+    /**
+     * Repair hint appended to endpoint-aspect diagnostics (YM404). A remedy,
+     * never a correction: the compiler still rejects the input.
+     */
+    readonly repair?: string;
 }
 /**
  * Safe, intentionally broad semantic constraints. A future licensed

package/dist/profile.js

@@ -137,6 +137,7 @@ export const relationshipPolicies = [
         id: 'assignment',
         intent: 'Allocate an active structure to behavior or responsibility',
         sourceAspects: ['active-structure'],
+        repair: 'assign from an active-structure element (an actor, component, or node), or use "association"',
     },
     { id: 'realization', intent: 'Fulfil a more abstract concept' },
     { id: 'serving', intent: 'Make behavior or an interface available' },
@@ -144,11 +145,13 @@ export const relationshipPolicies = [
         id: 'access',
         intent: 'Read, write, create, or use passive structure',
         targetAspects: ['passive-structure'],
+        repair: 'point "access" at passive structure (a business object, data object, or artifact), or use "association"',
     },
     {
         id: 'influence',
         intent: 'Affect a motivation concept',
         targetAspects: ['motivation'],
+        repair: 'point "influence" at a motivation concept (a goal, requirement, or principle), or use "association"',
     },
     { id: 'association', intent: 'Relevant connection with no stronger meaning' },
     {
@@ -156,6 +159,7 @@ export const relationshipPolicies = [
         intent: 'Express temporal or causal precedence',
         sourceAspects: ['behavior'],
         targetAspects: ['behavior'],
+        repair: 'use "flow" between active-structure elements, or introduce a behavior concept and "assignment"',
     },
     { id: 'flow', intent: 'Transfer information, value, goods, or material' },
     { id: 'specialization', intent: 'Express a more specific form' },

package/dist/projection.d.ts

@@ -40,3 +40,4 @@ export type ProjectionLoadResult = {
 export declare function loadProjection(source: WorkspaceSource): ProjectionLoadResult;
 export declare function evaluateProjection(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): ProjectionResult;
 export declare function renderProjectionMarkdown(result: ProjectionResult): string;
+export declare function renderBudgetedContext(result: ProjectionResult, budgetTokens: number): string;

package/dist/projection.js

@@ -181,3 +181,109 @@ export function renderProjectionMarkdown(result) {
     }
     return `${lines.join('\n')}\n`;
 }
+const estimateTokens = (text) => Math.ceil(text.length / 4);
+export function renderBudgetedContext(result, budgetTokens) {
+    const concepts = result.subjects.filter(({ type }) => type === 'concept');
+    const relationships = result.subjects.filter(({ type }) => type === 'relationship');
+    const title = result.presentation?.title ?? result.projection;
+    const header = [
+        `context ${result.projection} — ${title}`,
+        `subjects: ${concepts.length} concepts, ${relationships.length} relationships`,
+    ];
+    const subjectLines = [];
+    for (const concept of concepts) {
+        const name = claimValue(result.claims, concept.id, 'yarramate/concept/name');
+        const kind = claimValue(result.claims, concept.id, 'yarramate/concept/kind') ??
+            'unknown';
+        const status = claimValue(result.claims, concept.id, 'yarramate/lifecycle/status');
+        subjectLines.push(`- ${concept.id} [${kind.split('#')[1] ?? kind}]` +
+            `${name === undefined ? '' : ` ${name}`}` +
+            `${status === undefined ? '' : ` (${status})`}`);
+    }
+    const relationshipLines = [];
+    for (const relationship of relationships) {
+        const claim = result.claims.find(({ id, object }) => id === relationship.id && 'ref' in object);
+        if (claim !== undefined && 'ref' in claim.object) {
+            const kind = claim.predicate.split('#')[1] ?? claim.predicate;
+            relationshipLines.push(`- ${claim.subject} -${kind}-> ${claim.object.ref}`);
+        }
+    }
+    const descriptionLines = [];
+    for (const subject of result.subjects) {
+        const description = claimValue(result.claims, subject.id, 'yarramate/concept/description') ??
+            claimValue(result.claims, subject.id, 'yarramate/relationship/description');
+        if (description !== undefined) {
+            descriptionLines.push(`- ${subject.id}: ${description}`);
+        }
+    }
+    const detailPredicates = new Set([
+        'yarramate/ownership/owner',
+        'yarramate/constraint/requires',
+        'yarramate/reference/refers-to',
+        'yarramate/access/mode',
+        'yarramate/state/present-in',
+    ]);
+    const detailLines = [];
+    for (const claim of result.claims) {
+        if (!detailPredicates.has(claim.predicate))
+            continue;
+        const value = 'ref' in claim.object ? claim.object.ref : claim.object.value;
+        const predicate = claim.predicate.split('/').pop() ?? claim.predicate;
+        detailLines.push(`- ${claim.subject} ${predicate}: ${value}`);
+    }
+    // Ranked ladder: the two header lines always render; every other line —
+    // including the subject skeleton — competes for the remaining budget in
+    // priority order, and anything dropped is always announced rather than
+    // silently omitted.
+    const sections = [
+        { heading: 'relationships:', lines: relationshipLines },
+        { heading: 'descriptions:', lines: descriptionLines },
+        { heading: 'details:', lines: detailLines },
+    ];
+    const rendered = [...header];
+    const omitted = [];
+    let spent = estimateTokens(rendered.join('\n'));
+    let droppedSubjects = 0;
+    for (const line of subjectLines) {
+        const cost = estimateTokens(line);
+        if (spent + cost > budgetTokens) {
+            droppedSubjects += 1;
+            continue;
+        }
+        rendered.push(line);
+        spent += cost;
+    }
+    if (droppedSubjects > 0) {
+        omitted.push(`subjects ${droppedSubjects} omitted`);
+    }
+    for (const section of sections) {
+        if (section.lines.length === 0)
+            continue;
+        const kept = [section.heading];
+        let sectionSpent = estimateTokens(section.heading);
+        let dropped = 0;
+        for (const line of section.lines) {
+            const cost = estimateTokens(line);
+            if (spent + sectionSpent + cost > budgetTokens) {
+                dropped += 1;
+                continue;
+            }
+            kept.push(line);
+            sectionSpent += cost;
+        }
+        if (kept.length > 1) {
+            rendered.push('', ...kept);
+            spent += sectionSpent;
+        }
+        else {
+            dropped = section.lines.length;
+        }
+        if (dropped > 0) {
+            omitted.push(`${section.heading.replace(':', '')} ${dropped} omitted`);
+        }
+    }
+    if (omitted.length > 0) {
+        rendered.push('', `[budget ${budgetTokens}: ${omitted.join('; ')} — raise --budget or use JSON mode for the complete slice]`);
+    }
+    return `${rendered.join('\n')}\n`;
+}

package/dist/reconciliation.d.ts

@@ -1,9 +1,17 @@
+import type { SemanticGraph } from './compiler.js';
 import type { EvidenceLocator, EvidenceReport, EvidenceResult } from './evidence.js';
+export interface AssertedRelationship {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: string;
+    readonly name?: string;
+}
 export interface ReconciliationFinding {
     readonly target: {
         readonly type: 'subject' | 'claim';
         readonly id: string;
     };
+    readonly asserted?: AssertedRelationship;
     readonly result: Exclude<EvidenceResult, 'confirmed'>;
     readonly provider: string;
     readonly evidenceDocument: string;
@@ -23,4 +31,4 @@ export interface ReconciliationReport {
     };
     readonly findings: readonly ReconciliationFinding[];
 }
-export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[]): ReconciliationReport;
+export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[], graph?: SemanticGraph): ReconciliationReport;

package/dist/reconciliation.js

@@ -1,4 +1,32 @@
-export function reconcileEvidenceReports(workspace, reports) {
+const assertedRelationshipsByClaim = (graph) => {
+    const asserted = new Map();
+    if (graph === undefined)
+        return asserted;
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const names = new Map();
+    for (const claim of graph.claims) {
+        if (claim.predicate === 'yarramate/relationship/name' &&
+            'value' in claim.object) {
+            names.set(claim.subject, claim.object.value);
+        }
+    }
+    for (const claim of graph.claims) {
+        if (!relationshipIds.has(claim.id) || !('ref' in claim.object))
+            continue;
+        const name = names.get(claim.id);
+        asserted.set(claim.id, {
+            from: claim.subject,
+            to: claim.object.ref,
+            kind: claim.predicate,
+            ...(name === undefined ? {} : { name }),
+        });
+    }
+    return asserted;
+};
+export function reconcileEvidenceReports(workspace, reports, graph) {
+    const assertedByClaim = assertedRelationshipsByClaim(graph);
     const summary = {
         evidenceDocuments: reports.length,
         observations: 0,
@@ -22,10 +50,13 @@ export function reconcileEvidenceReports(workspace, reports) {
             else {
                 summary[observation.result] += 1;
             }
+            const target = 'subject' in observation
+                ? { type: 'subject', id: observation.subject }
+                : { type: 'claim', id: observation.claim };
+            const asserted = target.type === 'claim' ? assertedByClaim.get(target.id) : undefined;
             findings.push({
-                target: 'subject' in observation
-                    ? { type: 'subject', id: observation.subject }
-                    : { type: 'claim', id: observation.claim },
+                target,
+                ...(asserted === undefined ? {} : { asserted }),
                 result: observation.result,
                 provider: report.provider,
                 evidenceDocument: report.evidence,

package/dist/source-document.d.ts

@@ -1,4 +1,4 @@
-import type { ValidateFunction } from 'ajv';
+import type { ErrorObject, ValidateFunction } from 'ajv';
 import { LineCounter, parseDocument } from 'yaml';
 import type { Diagnostic, WorkspaceSource } from './compiler.js';
 export interface SourceLocation {
@@ -20,5 +20,7 @@ export type SourceDocumentResult<T> = {
     readonly diagnostics: readonly Diagnostic[];
 };
 export declare const diagnosticOrder: (left: Diagnostic, right: Diagnostic) => number;
+export declare const describeSchemaViolation: (error: Pick<ErrorObject, "keyword" | "message" | "params">) => string;
+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

@@ -4,6 +4,48 @@ export const diagnosticOrder = (left, right) => left.path.localeCompare(right.pa
     left.column - right.column ||
     left.code.localeCompare(right.code) ||
     left.message.localeCompare(right.message);
+export const describeSchemaViolation = (error) => {
+    const base = error.message ?? error.keyword;
+    if (error.keyword === 'const') {
+        return `${base}: expected ${JSON.stringify(error.params.allowedValue)}`;
+    }
+    if (error.keyword === 'enum' &&
+        Array.isArray(error.params.allowedValues)) {
+        const allowed = error.params.allowedValues;
+        const shown = allowed
+            .slice(0, 8)
+            .map((value) => JSON.stringify(value))
+            .join(', ');
+        return `${base}: ${shown}${allowed.length > 8 ? ', …' : ''}`;
+    }
+    return base;
+};
+const editDistance = (left, right) => {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= left.length; i += 1) {
+        let diagonal = previous[0];
+        previous[0] = i;
+        for (let j = 1; j <= right.length; j += 1) {
+            const above = previous[j];
+            previous[j] = Math.min(above + 1, previous[j - 1] + 1, diagonal + (left[i - 1] === right[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[right.length];
+};
+export const closestCandidate = (value, candidates) => {
+    const threshold = Math.max(2, Math.floor(value.length / 4));
+    let best;
+    let bestDistance = threshold + 1;
+    for (const candidate of [...candidates].sort()) {
+        const distance = editDistance(value.toLowerCase(), candidate.toLowerCase());
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+};
 export function locateSourcePath(sourcePath, yaml, lineCounter, yamlPath, pointer) {
     const node = yaml.getIn(yamlPath, true);
     const offset = typeof node === 'object' &&
@@ -62,7 +104,7 @@ export function loadSourceDocument(source, validate, schemaLabel) {
                     code: 'YM201',
                     message: property
                         ? `Property "${property}" is not allowed`
-                        : `${schemaLabel} schema violation: ${error.message ?? error.keyword}`,
+                        : `${schemaLabel} schema violation: ${describeSchemaViolation(error)}`,
                     ...location,
                 };
             })

package/dist/status-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runStatusCommand(options: readonly string[], cwd: string): CliResult;