@canon-protocol/sdk 8.0.0

package/dist/validation/rules/document/NamespacePrefixRule.d.ts

@@ -0,0 +1,10 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import type { IDocumentValidationRule } from './IDocumentValidationRule.js';
+export declare class NamespacePrefixRule implements IDocumentValidationRule {
+    private static readonly NAMESPACE_PREFIX_PATTERN;
+    readonly ruleName = "NamespacePrefix";
+    validate(document: CanonDocument): OntologyValidationError[];
+    private validateEntity;
+    private getSuggestionForPrefixedValue;
+}

package/dist/validation/rules/document/NamespacePrefixRule.js

@@ -0,0 +1,51 @@
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import { ValidationSeverity } from '../../ValidationSeverity.js';
+export class NamespacePrefixRule {
+    static NAMESPACE_PREFIX_PATTERN = /^(rdfs|xsd|owl|rdf|dc|foaf|skos|dct|dcterms|geo|time|prov|schema|og|dbo):/i;
+    ruleName = 'NamespacePrefix';
+    validate(document) {
+        const errors = [];
+        for (const [entityName, entityValue] of Object.entries(document.body)) {
+            if (entityValue && typeof entityValue === 'object' && !Array.isArray(entityValue)) {
+                this.validateEntity(entityName, entityValue, errors);
+            }
+        }
+        return errors;
+    }
+    validateEntity(entityName, entityDict, errors) {
+        for (const [propName, propValue] of Object.entries(entityDict)) {
+            const propValueStr = propValue?.toString() ?? '';
+            if (propValueStr && NamespacePrefixRule.NAMESPACE_PREFIX_PATTERN.test(propValueStr)) {
+                const suggestion = this.getSuggestionForPrefixedValue(propValueStr);
+                const rootEntity = entityName.split('.')[0];
+                const error = new OntologyValidationError();
+                error.ruleType = this.ruleName;
+                error.severity = ValidationSeverity.Error;
+                error.entityName = rootEntity; // Root entity for lookup
+                error.propertyName = entityName; // Full nested path for navigation
+                error.actualValue = propName; // Property to find at end of path
+                error.expectedValue = suggestion;
+                error.message = `Invalid namespace prefix '${propValueStr}'. Use '${suggestion}' without prefix.`;
+                error.suggestion = 'Canon YAML uses simple type names. Namespace resolution is handled through imports.';
+                errors.push(error);
+            }
+            if (propValue && typeof propValue === 'object' && !Array.isArray(propValue)) {
+                this.validateEntity(`${entityName}.${propName}`, propValue, errors);
+            }
+        }
+    }
+    getSuggestionForPrefixedValue(prefixedValue) {
+        const lowerValue = prefixedValue.toLowerCase();
+        if (lowerValue === 'rdfs:class' || lowerValue === 'owl:class') {
+            return 'Class';
+        }
+        if (lowerValue === 'rdfs:property' || lowerValue === 'rdf:property') {
+            return 'DatatypeProperty or ObjectProperty';
+        }
+        if (lowerValue.startsWith('xsd:')) {
+            return prefixedValue.substring(4);
+        }
+        const colonIndex = prefixedValue.indexOf(':');
+        return colonIndex >= 0 ? prefixedValue.substring(colonIndex + 1) : prefixedValue;
+    }
+}

package/dist/validation/rules/document/PropertyTypeSpecificityRule.d.ts

@@ -0,0 +1,11 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import type { IDocumentValidationRule } from './IDocumentValidationRule.js';
+export declare class PropertyTypeSpecificityRule implements IDocumentValidationRule {
+    private static readonly XSD_TYPES;
+    readonly ruleName = "PropertyTypeSpecificity";
+    validate(document: CanonDocument): OntologyValidationError[];
+    private determinePropertyType;
+    private getPropertyValue;
+    private isPropertyDefinedAsClass;
+}

package/dist/validation/rules/document/PropertyTypeSpecificityRule.js

@@ -0,0 +1,89 @@
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import { ValidationSeverity } from '../../ValidationSeverity.js';
+export class PropertyTypeSpecificityRule {
+    static XSD_TYPES = new Set([
+        'string', 'integer', 'int', 'long', 'short', 'byte',
+        'decimal', 'float', 'double', 'boolean', 'bool',
+        'datetime', 'date', 'time', 'duration',
+        'anyuri', 'anysimpletype',
+        'nonnegativeinteger', 'positiveinteger',
+        'negativeinteger', 'nonpositiveinteger',
+        'unsignedint', 'unsignedlong', 'unsignedshort', 'unsignedbyte',
+        'base64binary', 'hexbinary'
+    ]);
+    ruleName = 'PropertyTypeSpecificity';
+    validate(document) {
+        const errors = [];
+        if (document.metadata?.namespace_?.publisher === 'canon-protocol.org' &&
+            document.metadata?.namespace_?.package_?.startsWith('core-')) {
+            return errors; // Empty list - no validation errors
+        }
+        const propertyDefinedAsClass = this.isPropertyDefinedAsClass(document);
+        for (const [entityName, entityValue] of Object.entries(document.body)) {
+            if (entityValue && typeof entityValue === 'object' && !Array.isArray(entityValue)) {
+                const entityDict = entityValue;
+                const typeValue = entityDict['type'];
+                if (typeValue) {
+                    const invalidTypes = [];
+                    if (Array.isArray(typeValue)) {
+                        for (const type of typeValue) {
+                            const typeStr = type?.toString();
+                            if (typeStr && typeStr === 'Property' && !propertyDefinedAsClass) {
+                                invalidTypes.push(typeStr);
+                            }
+                        }
+                    }
+                    else {
+                        const typeStr = typeValue?.toString();
+                        if (typeStr && typeStr === 'Property' && !propertyDefinedAsClass) {
+                            invalidTypes.push(typeStr);
+                        }
+                    }
+                    for (const invalidType of invalidTypes) {
+                        const rangeValue = this.getPropertyValue(entityDict, 'range');
+                        const suggestedType = this.determinePropertyType(rangeValue);
+                        const error = new OntologyValidationError();
+                        error.ruleType = this.ruleName;
+                        error.severity = ValidationSeverity.Error;
+                        error.entityName = entityName;
+                        error.propertyName = 'type';
+                        error.actualValue = invalidType;
+                        error.expectedValue = suggestedType;
+                        error.message = `Invalid property type '${invalidType}'. Use '${suggestedType}' instead.`;
+                        error.suggestion = 'Properties should specify their type: DatatypeProperty for data values, ObjectProperty for relationships.';
+                        errors.push(error);
+                    }
+                }
+            }
+        }
+        return errors;
+    }
+    determinePropertyType(rangeValue) {
+        if (!rangeValue || rangeValue.trim().length === 0) {
+            return 'DatatypeProperty or ObjectProperty';
+        }
+        if (PropertyTypeSpecificityRule.XSD_TYPES.has(rangeValue.toLowerCase())) {
+            return 'DatatypeProperty';
+        }
+        if (/^[A-Z]/.test(rangeValue)) {
+            return 'ObjectProperty';
+        }
+        return 'DatatypeProperty or ObjectProperty';
+    }
+    getPropertyValue(dict, propertyName) {
+        const value = dict[propertyName];
+        return value ? value.toString() : null;
+    }
+    isPropertyDefinedAsClass(document) {
+        const propertyEntity = document.body['Property'];
+        if (propertyEntity && typeof propertyEntity === 'object' && !Array.isArray(propertyEntity)) {
+            const entityDict = propertyEntity;
+            const typeValue = entityDict['type'];
+            if (typeValue) {
+                const typeStr = typeValue.toString();
+                return typeStr === 'Class' || typeStr.endsWith('.Class');
+            }
+        }
+        return false;
+    }
+}

package/dist/validation/rules/document/ResourceNamingRule.d.ts

@@ -0,0 +1,12 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import type { IDocumentValidationRule } from './IDocumentValidationRule.js';
+export declare class ResourceNamingRule implements IDocumentValidationRule {
+    private static readonly RESERVED_WORDS;
+    private static readonly VALID_PROPERTIES;
+    private static readonly VALID_NAME_PATTERN;
+    private static readonly VALID_PROPERTY_NAME_PATTERN;
+    readonly ruleName = "ResourceNaming";
+    validate(document: CanonDocument): OntologyValidationError[];
+    private validatePropertyNames;
+}

package/dist/validation/rules/document/ResourceNamingRule.js

@@ -0,0 +1,79 @@
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import { ValidationSeverity } from '../../ValidationSeverity.js';
+export class ResourceNamingRule {
+    static RESERVED_WORDS = new Set([
+        'canon',
+        'imports',
+        'namespace',
+        'type',
+        'label',
+        'comment',
+        'subclassof',
+        'domain',
+        'range',
+        'required',
+        'functional'
+    ]);
+    static VALID_PROPERTIES = new Set([
+        'type', 'label', 'comment', 'subClassOf', 'subPropertyOf', 'domain', 'range',
+        'required', 'functional', 'inverseOf', 'transitive', 'symmetric', 'inverseFunctional'
+    ]);
+    static VALID_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+    static VALID_PROPERTY_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.]*$/;
+    ruleName = 'ResourceNaming';
+    validate(document) {
+        const errors = [];
+        for (const [entityName, entityValue] of Object.entries(document.body)) {
+            if (ResourceNamingRule.RESERVED_WORDS.has(entityName.toLowerCase())) {
+                const error = new OntologyValidationError();
+                error.ruleType = this.ruleName;
+                error.severity = ValidationSeverity.Error;
+                error.entityName = entityName;
+                error.message = `Entity name '${entityName}' is a reserved word and cannot be used.`;
+                error.suggestion = "Choose a different name that doesn't conflict with Canon reserved words.";
+                errors.push(error);
+                continue;
+            }
+            if (!ResourceNamingRule.VALID_NAME_PATTERN.test(entityName)) {
+                let suggestion;
+                if (/^\d/.test(entityName)) {
+                    suggestion = 'Entity names must start with a letter, not a number.';
+                }
+                else if (entityName.includes(' ')) {
+                    suggestion = 'Entity names cannot contain spaces. Use camelCase or underscores instead.';
+                }
+                else {
+                    suggestion = 'Entity names must start with a letter and contain only letters, numbers, and underscores.';
+                }
+                const error = new OntologyValidationError();
+                error.ruleType = this.ruleName;
+                error.severity = ValidationSeverity.Error;
+                error.entityName = entityName;
+                error.message = `Invalid entity name '${entityName}'. ${suggestion}`;
+                error.suggestion = suggestion;
+                errors.push(error);
+            }
+            if (entityValue && typeof entityValue === 'object' && !Array.isArray(entityValue)) {
+                this.validatePropertyNames(entityName, entityValue, errors);
+            }
+        }
+        return errors;
+    }
+    validatePropertyNames(entityName, entityDict, errors) {
+        for (const propertyName of Object.keys(entityDict)) {
+            if (ResourceNamingRule.VALID_PROPERTIES.has(propertyName)) {
+                continue;
+            }
+            if (!ResourceNamingRule.VALID_PROPERTY_NAME_PATTERN.test(propertyName)) {
+                const error = new OntologyValidationError();
+                error.ruleType = this.ruleName;
+                error.severity = ValidationSeverity.Warning;
+                error.entityName = entityName;
+                error.propertyName = propertyName;
+                error.message = `Property name '${propertyName}' in entity '${entityName}' doesn't follow naming conventions.`;
+                error.suggestion = 'Property names should start with a letter and contain only letters, numbers, and underscores.';
+                errors.push(error);
+            }
+        }
+    }
+}

package/dist/validation/rules/document/SubjectCanonTypeRequiredRule.d.ts

@@ -0,0 +1,7 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import type { IDocumentValidationRule } from './IDocumentValidationRule.js';
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+export declare class SubjectCanonTypeRequiredRule implements IDocumentValidationRule {
+    get ruleName(): string;
+    validate(document: CanonDocument): OntologyValidationError[];
+}

package/dist/validation/rules/document/SubjectCanonTypeRequiredRule.js

@@ -0,0 +1,33 @@
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import { ValidationSeverity } from '../../ValidationSeverity.js';
+export class SubjectCanonTypeRequiredRule {
+    get ruleName() {
+        return 'SubjectCanonTypeRequired';
+    }
+    validate(document) {
+        const errors = [];
+        for (const [entityName, entityDef] of Object.entries(document.body)) {
+            if (typeof entityDef !== 'object' || entityDef === null || Array.isArray(entityDef)) {
+                continue;
+            }
+            const entity = entityDef;
+            const hasType = 'type' in entity;
+            const typeValue = entity['type']?.toString().trim();
+            if (!hasType || !typeValue) {
+                const error = new OntologyValidationError();
+                error.ruleType = this.ruleName;
+                error.severity = ValidationSeverity.Error;
+                error.entityName = entityName;
+                error.propertyName = 'type';
+                error.message = `Subject Canon '${entityName}' must have a 'type' property.`;
+                error.suggestion =
+                    "Add a type statement like:\n  type: Scene\n\n" +
+                        "Only embedded objects can infer type from their parent property's range. " +
+                        "Subject Canons (top-level entities) must explicitly declare their type.";
+                error.expectedValue = "A valid class name (Scene, Character, Story, etc.)";
+                errors.push(error);
+            }
+        }
+        return errors;
+    }
+}

package/dist/validation/rules/document/index.d.ts

@@ -0,0 +1,6 @@
+export type { IDocumentValidationRule } from './IDocumentValidationRule.js';
+export { NamespacePrefixRule } from './NamespacePrefixRule.js';
+export { ResourceNamingRule } from './ResourceNamingRule.js';
+export { PropertyTypeSpecificityRule } from './PropertyTypeSpecificityRule.js';
+export { SubjectCanonTypeRequiredRule } from './SubjectCanonTypeRequiredRule.js';
+export { EmbeddedCanonNoExplicitTypeRule } from './EmbeddedCanonNoExplicitTypeRule.js';

package/dist/validation/rules/document/index.js

@@ -0,0 +1,5 @@
+export { NamespacePrefixRule } from './NamespacePrefixRule.js';
+export { ResourceNamingRule } from './ResourceNamingRule.js';
+export { PropertyTypeSpecificityRule } from './PropertyTypeSpecificityRule.js';
+export { SubjectCanonTypeRequiredRule } from './SubjectCanonTypeRequiredRule.js';
+export { EmbeddedCanonNoExplicitTypeRule } from './EmbeddedCanonNoExplicitTypeRule.js';

package/dist/validation/rules/normalizeToStringList.d.ts

@@ -0,0 +1 @@
+export declare function normalizeToStringList(value: unknown): string[];

package/dist/validation/rules/normalizeToStringList.js

@@ -0,0 +1,9 @@
+export function normalizeToStringList(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map(item => item?.toString() ?? '')
+            .filter(s => s.length > 0);
+    }
+    const str = value?.toString();
+    return str ? [str] : [];
+}

package/dist/validation/rules/repository/AmbiguousReferenceRule.d.ts

@@ -0,0 +1,14 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import type { ICanonDocumentRepository } from '@canon-protocol/types/document/models';
+import type { IRepositoryValidationRule } from './IRepositoryValidationRule.js';
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+export declare class AmbiguousReferenceRule implements IRepositoryValidationRule {
+    get ruleName(): string;
+    validateAsync(document: CanonDocument, repository: ICanonDocumentRepository): Promise<OntologyValidationError[]>;
+    private buildEntitySourceMapAsync;
+    private collectEntitiesRecursivelyAsync;
+    private validateEntityReferences;
+    private validatePropertyValue;
+    private createAmbiguityError;
+    private findAliasForNamespace;
+}

package/dist/validation/rules/repository/AmbiguousReferenceRule.js

@@ -0,0 +1,155 @@
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+import { ValidationSeverity } from '../../ValidationSeverity.js';
+export class AmbiguousReferenceRule {
+    get ruleName() {
+        return 'AmbiguousReference';
+    }
+    async validateAsync(document, repository) {
+        const errors = [];
+        const entitySourceMap = await this.buildEntitySourceMapAsync(document, repository);
+        for (const [entityName, entityValue] of Object.entries(document.body)) {
+            if (typeof entityValue === 'object' && entityValue !== null && !Array.isArray(entityValue)) {
+                this.validateEntityReferences(entityName, entityValue, entitySourceMap, document, errors);
+            }
+        }
+        return errors;
+    }
+    async buildEntitySourceMapAsync(document, repository) {
+        const entitySources = new Map();
+        const visitedNamespaces = new Set();
+        for (const entityName of Object.keys(document.body)) {
+            const docNamespace = document.metadata.namespace_?.toString() ?? '';
+            if (!entitySources.has(entityName)) {
+                entitySources.set(entityName, []);
+            }
+            entitySources.get(entityName).push(`(local:${docNamespace})`);
+        }
+        if (document.metadata.imports) {
+            for (const [publisher, imports] of Object.entries(document.metadata.imports)) {
+                for (const import_ of imports) {
+                    const importedDoc = await repository.getHighestCompatibleVersionAsync(publisher, import_);
+                    if (importedDoc) {
+                        await this.collectEntitiesRecursivelyAsync(importedDoc, entitySources, visitedNamespaces, repository);
+                    }
+                }
+            }
+        }
+        return entitySources;
+    }
+    async collectEntitiesRecursivelyAsync(document, entitySources, visitedNamespaces, repository) {
+        const docNamespace = document.metadata.namespace_?.toString() ?? '';
+        if (visitedNamespaces.has(docNamespace)) {
+            return;
+        }
+        visitedNamespaces.add(docNamespace);
+        for (const entityName of Object.keys(document.body)) {
+            if (!entitySources.has(entityName)) {
+                entitySources.set(entityName, []);
+            }
+            const sources = entitySources.get(entityName);
+            if (!sources.includes(docNamespace)) {
+                sources.push(docNamespace);
+            }
+        }
+        if (document.metadata.imports) {
+            for (const [publisher, imports] of Object.entries(document.metadata.imports)) {
+                for (const import_ of imports) {
+                    const importedDoc = await repository.getHighestCompatibleVersionAsync(publisher, import_);
+                    if (importedDoc) {
+                        await this.collectEntitiesRecursivelyAsync(importedDoc, entitySources, visitedNamespaces, repository);
+                    }
+                }
+            }
+        }
+    }
+    validateEntityReferences(entityPath, entity, entitySourceMap, document, errors) {
+        for (const [propKey, propValue] of Object.entries(entity)) {
+            const propertyName = propKey;
+            if (propertyName && !propertyName.includes('.')) {
+                const sources = entitySourceMap.get(propertyName);
+                if (sources && sources.length > 1) {
+                    const hasLocal = sources.some(s => s.startsWith('(local:'));
+                    if (!hasLocal) {
+                        const externalSources = sources.filter(s => !s.startsWith('(local:'));
+                        if (externalSources.length > 1) {
+                            errors.push(this.createAmbiguityError(entityPath, propertyName, `Property '${propertyName}'`, externalSources, document, true, propertyName));
+                        }
+                    }
+                }
+            }
+            this.validatePropertyValue(entityPath, propertyName, propValue, entitySourceMap, document, errors);
+        }
+    }
+    validatePropertyValue(entityPath, propertyName, value, entitySourceMap, document, errors) {
+        if (value == null) {
+            return;
+        }
+        if (typeof value === 'string' && !value.includes('.')) {
+            const sources = entitySourceMap.get(value);
+            if (sources && sources.length > 1) {
+                const hasLocal = sources.some(s => s.startsWith('(local:'));
+                if (!hasLocal) {
+                    const externalSources = sources.filter(s => !s.startsWith('(local:'));
+                    if (externalSources.length > 1) {
+                        errors.push(this.createAmbiguityError(entityPath, propertyName, `Reference '${value}'`, externalSources, document, false, value));
+                    }
+                }
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                const itemPath = `${entityPath}.${propertyName}[${i}]`;
+                this.validatePropertyValue(itemPath, null, value[i], entitySourceMap, document, errors);
+            }
+        }
+        else if (typeof value === 'object' && !Array.isArray(value)) {
+            const nestedPath = propertyName ? `${entityPath}.${propertyName}` : entityPath;
+            this.validateEntityReferences(nestedPath, value, entitySourceMap, document, errors);
+        }
+    }
+    createAmbiguityError(entityPath, propertyName, description, sources, document, _isProperty, ambiguousValue) {
+        const suggestions = [];
+        for (const source of sources) {
+            const matchingAlias = this.findAliasForNamespace(document, source);
+            if (matchingAlias) {
+                const entityName = propertyName?.split('.').pop() ?? propertyName;
+                suggestions.push(`${matchingAlias}.${entityName}`);
+            }
+        }
+        const suggestionText = suggestions.length > 0
+            ? `Use one of: ${suggestions.map(s => `'${s}'`).join(', ')}`
+            : `Add aliases to imports and use qualified names (e.g., 'alias.${propertyName}')`;
+        const sourcesText = sources.map(s => `   • ${s}`).join('\n');
+        const rootEntity = entityPath.split('.')[0];
+        const propertyPath = entityPath.includes('.') ? entityPath : propertyName;
+        const error = new OntologyValidationError();
+        error.ruleType = this.ruleName;
+        error.severity = ValidationSeverity.Error;
+        error.entityName = rootEntity; // Root entity for lookup
+        if (propertyPath) {
+            error.propertyName = propertyPath; // Property name for simple, full path for nested
+        }
+        const valueToUse = ambiguousValue ?? propertyName;
+        if (valueToUse) {
+            error.actualValue = valueToUse; // Use actual ambiguous value if provided, otherwise property name
+        }
+        error.message = `${description} is ambiguous - defined in multiple imported namespaces`;
+        error.suggestion = `${suggestionText}\n\nDefined in:\n${sourcesText}`;
+        error.expectedValue = 'Unambiguous reference (use namespace alias to disambiguate)';
+        return error;
+    }
+    findAliasForNamespace(document, namespaceString) {
+        if (!document.metadata.imports) {
+            return null;
+        }
+        for (const [publisher, imports] of Object.entries(document.metadata.imports)) {
+            for (const import_ of imports) {
+                const importNamespace = `${publisher}/${import_.packageName}@${import_.version}`;
+                if (importNamespace === namespaceString && import_.alias) {
+                    return import_.alias;
+                }
+            }
+        }
+        return null;
+    }
+}

package/dist/validation/rules/repository/ClassDefinitionRule.d.ts

@@ -0,0 +1,12 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import type { ICanonDocumentRepository } from '@canon-protocol/types/document/models';
+import type { IRepositoryValidationRule } from './IRepositoryValidationRule.js';
+import { OntologyValidationError } from '../../OntologyValidationError.js';
+export declare class ClassDefinitionRule implements IRepositoryValidationRule {
+    private readonly builtInClasses;
+    get ruleName(): string;
+    validateAsync(document: CanonDocument, repository: ICanonDocumentRepository): Promise<OntologyValidationError[]>;
+    private checkNestedTypes;
+    private isClassEntity;
+    private isDefinitionType;
+}