@canon-protocol/sdk 8.0.0

package/dist/ctl/CtlParser.d.ts

@@ -0,0 +1,10 @@
+import type { CtlDocument } from '@canon-protocol/types/ctl/models/types';
+import type { CtlParser as ICtlParser } from '@canon-protocol/types/ctl/parsing/types';
+export declare class CtlParser implements ICtlParser {
+    parse(content: string, filePath?: string | null): CtlDocument;
+    parseFileAsync(filePath: string): Promise<CtlDocument>;
+    private parseWithFrontmatter;
+    private parseInline;
+    private parseMarkdownBody;
+    private buildAliasMap;
+}

package/dist/ctl/CtlParser.js

@@ -0,0 +1,331 @@
+import { VersionOperator } from '@canon-protocol/types/document/models/enums';
+import { CtlCanonUri } from './CtlCanonUri.js';
+import * as yaml from 'js-yaml';
+const CANON_LINK_REGEX = /\[([^\]]+)\]\((canon:\/\/[^)]+)\)/gi;
+const CAN_SHORT_LINK_REGEX = /\[([^\]]+)\]\(can:\/\/([^)]+)\)/gi;
+const CODE_BLOCK_REGEX = /```[\s\S]*?```|`[^`]+`/g;
+const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+function createVersion(major, minor, patch) {
+    const versionStr = `${major}.${minor}.${patch}`;
+    return {
+        major,
+        minor,
+        patch,
+        toString: () => versionStr,
+        equals: (obj) => obj?.major === major && obj?.minor === minor && obj?.patch === patch,
+        getHashCode: () => (major << 20) | (minor << 10) | patch,
+        compareTo: (other) => {
+            if (major !== other.major)
+                return major - other.major;
+            if (minor !== other.minor)
+                return minor - other.minor;
+            return patch - other.patch;
+        }
+    };
+}
+function createImport(publisher, packageName, version, versionOperator, alias) {
+    const operatorSymbol = versionOperator === VersionOperator.Compatible ? '~' :
+        versionOperator === VersionOperator.Major ? '^' :
+            versionOperator === VersionOperator.Exact ? '=' : '*';
+    const package_ = `${packageName} ${operatorSymbol} ${version}`;
+    return {
+        package_,
+        publisher,
+        packageName,
+        versionOperator,
+        version,
+        alias,
+        get minVersion() { return version; },
+        get maxVersion() { return version; },
+        toEmbeddedObject() {
+            const obj = {
+                package: packageName,
+                version: version.toString()
+            };
+            if (alias)
+                obj.alias = alias;
+            if (versionOperator !== VersionOperator.Exact)
+                obj.match = operatorSymbol;
+            return obj;
+        },
+        toString() { return package_; }
+    };
+}
+export class CtlParser {
+    parse(content, filePath) {
+        if (content == null) {
+            throw new Error('Content cannot be null');
+        }
+        if (content.charCodeAt(0) === 0xFEFF) {
+            content = content.substring(1);
+        }
+        const frontmatterMatch = FRONTMATTER_REGEX.exec(content);
+        if (frontmatterMatch) {
+            return this.parseWithFrontmatter(content, frontmatterMatch, filePath ?? null);
+        }
+        else {
+            return this.parseInline(content, filePath ?? null);
+        }
+    }
+    async parseFileAsync(filePath) {
+        if (!filePath || filePath.trim().length === 0) {
+            throw new Error('File path cannot be null or empty');
+        }
+        const fs = await import('fs');
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return this.parse(content, filePath);
+    }
+    parseWithFrontmatter(content, frontmatterMatch, filePath) {
+        const frontmatterYaml = frontmatterMatch[1];
+        const markdownBody = content.substring(frontmatterMatch[0].length);
+        let metadata = null;
+        let aliasMap = new Map();
+        try {
+            const yamlRoot = yaml.load(frontmatterYaml);
+            if (!yamlRoot) {
+                throw new Error('Frontmatter YAML is empty');
+            }
+            if (!yamlRoot.imports || !Array.isArray(yamlRoot.imports)) {
+                throw new Error("Frontmatter must contain an 'imports' sequence");
+            }
+            const importsByPublisher = {};
+            for (const entry of yamlRoot.imports) {
+                if (!entry || typeof entry !== 'object') {
+                    throw new Error("Each import entry must be a mapping with 'publisher' and 'packages'");
+                }
+                const publisher = entry.publisher?.toString();
+                if (!publisher) {
+                    throw new Error("Each import entry requires a 'publisher' property");
+                }
+                if (!entry.packages || !Array.isArray(entry.packages)) {
+                    throw new Error(`Import entry for publisher '${publisher}' requires a 'packages' sequence`);
+                }
+                if (!importsByPublisher[publisher]) {
+                    importsByPublisher[publisher] = [];
+                }
+                for (const pkgEntry of entry.packages) {
+                    if (!pkgEntry || typeof pkgEntry !== 'object') {
+                        throw new Error(`Each package in publisher '${publisher}' must be a mapping`);
+                    }
+                    const versionStr = pkgEntry.version?.toString() ?? '1.0.0';
+                    const versionParts = versionStr.split('.').map(Number);
+                    const version = createVersion(versionParts[0] || 0, versionParts[1] || 0, versionParts[2] || 0);
+                    const matchStr = pkgEntry.match?.toString();
+                    const versionOperator = matchStr === '^' ? VersionOperator.Major :
+                        matchStr === '~' ? VersionOperator.Compatible :
+                            matchStr === '*' ? VersionOperator.Any :
+                                VersionOperator.Exact;
+                    const import_ = createImport(publisher, pkgEntry.package?.toString() ?? '', version, versionOperator, pkgEntry.alias?.toString() ?? null);
+                    importsByPublisher[publisher].push(import_);
+                }
+            }
+            const allImportsList = [];
+            for (const imports of Object.values(importsByPublisher)) {
+                allImportsList.push(...imports);
+            }
+            metadata = {
+                namespace_: undefined,
+                imports: importsByPublisher,
+                get allImports() { return allImportsList; }
+            };
+            aliasMap = this.buildAliasMap(importsByPublisher);
+        }
+        catch (ex) {
+            const errorRef = {
+                displayText: '(frontmatter)',
+                rawUri: '',
+                startOffset: 0,
+                endOffset: frontmatterMatch[0].length,
+                line: 1,
+                column: 1,
+                isResolved: false,
+                error: `Failed to parse frontmatter: ${ex.message}`,
+                get fullMarkdownLink() { return `[${this.displayText}](${this.rawUri})`; }
+            };
+            return createCtlDocument({
+                metadata: null,
+                rawMarkdown: markdownBody,
+                frontmatterLength: frontmatterMatch[0].length,
+                filePath,
+                references: [errorRef]
+            });
+        }
+        const bodyReferences = this.parseMarkdownBody(markdownBody, aliasMap, frontmatterMatch[0].length);
+        return createCtlDocument({
+            metadata,
+            rawMarkdown: markdownBody,
+            frontmatterLength: frontmatterMatch[0].length,
+            filePath,
+            references: bodyReferences
+        });
+    }
+    parseInline(content, filePath) {
+        const references = this.parseMarkdownBody(content, new Map(), 0);
+        return createCtlDocument({
+            metadata: null,
+            rawMarkdown: content,
+            frontmatterLength: 0,
+            filePath,
+            references
+        });
+    }
+    parseMarkdownBody(markdown, aliasMap, offsetAdjustment) {
+        const references = [];
+        const codeBlockRanges = findCodeBlockRanges(markdown);
+        const canonRegex = new RegExp(CANON_LINK_REGEX.source, 'gi');
+        let match;
+        while ((match = canonRegex.exec(markdown)) !== null) {
+            if (isInsideCodeBlock(match.index, codeBlockRanges))
+                continue;
+            const displayText = match[1];
+            const rawUri = match[2];
+            const { line, column } = getLineAndColumn(markdown, match.index);
+            const reference = {
+                displayText,
+                rawUri,
+                startOffset: match.index + offsetAdjustment,
+                endOffset: match.index + match[0].length + offsetAdjustment,
+                line,
+                column,
+                isResolved: false,
+                get fullMarkdownLink() { return `[${this.displayText}](${this.rawUri})`; }
+            };
+            try {
+                reference.parsedUri = CtlCanonUri.parse(rawUri);
+            }
+            catch (ex) {
+                reference.error = ex.message;
+            }
+            references.push(reference);
+        }
+        const canShortRegex = new RegExp(CAN_SHORT_LINK_REGEX.source, 'gi');
+        while ((match = canShortRegex.exec(markdown)) !== null) {
+            if (isInsideCodeBlock(match.index, codeBlockRanges))
+                continue;
+            const displayText = match[1];
+            const linkPath = match[2];
+            const { line, column } = getLineAndColumn(markdown, match.index);
+            let resolvedUri = null;
+            let error = null;
+            try {
+                resolvedUri = resolveCanLink(linkPath, aliasMap);
+            }
+            catch (ex) {
+                error = ex.message;
+            }
+            const reference = {
+                displayText,
+                rawUri: resolvedUri ?? `can://${linkPath}`,
+                startOffset: match.index + offsetAdjustment,
+                endOffset: match.index + match[0].length + offsetAdjustment,
+                line,
+                column,
+                isResolved: false,
+                error,
+                get fullMarkdownLink() { return `[${this.displayText}](${this.rawUri})`; }
+            };
+            if (resolvedUri != null && error == null) {
+                try {
+                    reference.parsedUri = CtlCanonUri.parse(resolvedUri);
+                }
+                catch (ex) {
+                    reference.error = ex.message;
+                }
+            }
+            references.push(reference);
+        }
+        references.sort((a, b) => a.startOffset - b.startOffset);
+        return references;
+    }
+    buildAliasMap(imports) {
+        const aliasMap = new Map();
+        for (const [publisher, importList] of Object.entries(imports)) {
+            for (const import_ of importList) {
+                const alias = import_.alias ?? import_.packageName;
+                aliasMap.set(alias.toLowerCase(), {
+                    publisher,
+                    package_: import_.packageName,
+                    version: import_.version
+                });
+            }
+        }
+        return aliasMap;
+    }
+}
+function createCtlDocument(init) {
+    return {
+        metadata: init.metadata,
+        get hasFrontmatter() { return init.metadata != null; },
+        rawMarkdown: init.rawMarkdown,
+        frontmatterLength: init.frontmatterLength,
+        filePath: init.filePath,
+        references: init.references,
+        get referenceCount() { return init.references.length; },
+        get allReferencesResolved() { return init.references.every((r) => r.isResolved); },
+        get unresolvedReferences() { return init.references.filter((r) => !r.isResolved); },
+        get errorReferences() { return init.references.filter((r) => r.error != null); }
+    };
+}
+function findCodeBlockRanges(markdown) {
+    const ranges = [];
+    const regex = new RegExp(CODE_BLOCK_REGEX.source, 'g');
+    let match;
+    while ((match = regex.exec(markdown)) !== null) {
+        ranges.push([match.index, match.index + match[0].length]);
+    }
+    return ranges;
+}
+function isInsideCodeBlock(offset, codeBlockRanges) {
+    for (const [start, end] of codeBlockRanges) {
+        if (offset >= start && offset < end)
+            return true;
+    }
+    return false;
+}
+function getLineAndColumn(text, offset) {
+    let line = 1;
+    let column = 1;
+    for (let i = 0; i < offset && i < text.length; i++) {
+        if (text[i] === '\n') {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column };
+}
+function resolveCanLink(linkPath, aliasMap) {
+    if (!linkPath || linkPath.trim().length === 0) {
+        throw new Error('can:// link cannot be empty');
+    }
+    if (aliasMap.size === 0) {
+        throw new Error('can:// links require frontmatter with imports');
+    }
+    let alias = null;
+    let entityName = linkPath;
+    const dotIndex = linkPath.indexOf('.');
+    if (dotIndex > 0) {
+        alias = linkPath.substring(0, dotIndex);
+        entityName = linkPath.substring(dotIndex + 1);
+        if (!entityName || entityName.trim().length === 0) {
+            throw new Error(`Resource name required after alias '${alias}.'`);
+        }
+    }
+    if (alias != null) {
+        const import_ = aliasMap.get(alias.toLowerCase());
+        if (!import_) {
+            const availableAliases = Array.from(aliasMap.keys()).join(', ');
+            throw new Error(`Unknown alias: '${alias}'. Available: ${availableAliases}`);
+        }
+        return `canon://${import_.publisher}/${import_.package_}@${import_.version}/${entityName}`;
+    }
+    else {
+        const firstImport = aliasMap.values().next().value;
+        if (!firstImport) {
+            throw new Error(`Cannot resolve '${entityName}': no imports defined`);
+        }
+        return `canon://${firstImport.publisher}/${firstImport.package_}@${firstImport.version}/${entityName}`;
+    }
+}

package/dist/ctl/CtlValidator.d.ts

@@ -0,0 +1,12 @@
+import type { CtlDocument, CtlValidationResult } from '@canon-protocol/types/ctl/models/types';
+import type { CtlValidator as ICtlValidator } from '@canon-protocol/types/ctl/validation/types';
+import type { ICanonDocumentRepository } from '@canon-protocol/types/document/models';
+export declare class CtlValidator implements ICtlValidator {
+    private readonly repository;
+    constructor(repository: ICanonDocumentRepository);
+    validateAsync(document: CtlDocument): Promise<CtlValidationResult>;
+    private resolveReference;
+    private resolveResource;
+    private resolveDeepLink;
+    private createError;
+}

package/dist/ctl/CtlValidator.js

@@ -0,0 +1,207 @@
+import { CtlValidationErrorType, CtlValidationSeverity } from '@canon-protocol/types/ctl/models/enums';
+import { CtlCanonUriType, PathSegmentType } from '@canon-protocol/types/ctl/parsing/enums';
+export class CtlValidator {
+    repository;
+    constructor(repository) {
+        if (!repository) {
+            throw new Error('Repository is required for CTL validation');
+        }
+        this.repository = repository;
+    }
+    async validateAsync(document) {
+        if (!document) {
+            throw new Error('Document cannot be null');
+        }
+        const errors = [];
+        const warnings = [];
+        for (const reference of document.references) {
+            if (!reference.parsedUri) {
+                errors.push({
+                    errorType: CtlValidationErrorType.InvalidUri,
+                    severity: CtlValidationSeverity.Error,
+                    message: reference.error ?? 'Failed to parse Canon URI',
+                    reference,
+                    line: reference.line,
+                    column: reference.column,
+                    toString() {
+                        const location = this.line != null ? `(${this.line}:${this.column})` : '';
+                        return `${CtlValidationSeverity[this.severity]}: ${this.message} ${location}`.trim();
+                    }
+                });
+                continue;
+            }
+            try {
+                await this.resolveReference(reference, errors, warnings);
+            }
+            catch (ex) {
+                errors.push({
+                    errorType: CtlValidationErrorType.ParseError,
+                    severity: CtlValidationSeverity.Error,
+                    message: `Error resolving reference: ${ex.message}`,
+                    reference,
+                    line: reference.line,
+                    column: reference.column,
+                    toString() {
+                        const location = this.line != null ? `(${this.line}:${this.column})` : '';
+                        return `${CtlValidationSeverity[this.severity]}: ${this.message} ${location}`.trim();
+                    }
+                });
+            }
+        }
+        const result = {
+            isValid: errors.length === 0,
+            document,
+            errors,
+            warnings,
+            get totalReferences() { return document.referenceCount; },
+            get resolvedReferences() { return document.references.filter((r) => r.isResolved).length; },
+            get summary() {
+                if (errors.length === 0) {
+                    return `All ${document.referenceCount} references validated`;
+                }
+                const resolvedCount = document.references.filter((r) => r.isResolved).length;
+                return `${errors.length} error(s), ${resolvedCount}/${document.referenceCount} references resolved`;
+            }
+        };
+        return result;
+    }
+    async resolveReference(reference, errors, _warnings) {
+        const uri = reference.parsedUri;
+        switch (uri.uriType) {
+            case CtlCanonUriType.Resource:
+                await this.resolveResource(reference, errors);
+                break;
+            case CtlCanonUriType.DeepLink:
+                await this.resolveDeepLink(reference, errors);
+                break;
+            default:
+                errors.push({
+                    errorType: CtlValidationErrorType.InvalidUri,
+                    severity: CtlValidationSeverity.Error,
+                    message: `Unsupported URI type: ${uri.uriType}. CTL only supports resource references.`,
+                    reference,
+                    line: reference.line,
+                    column: reference.column,
+                    suggestion: 'Use resource URIs: canon://publisher/package@version/resource',
+                    toString() {
+                        const location = this.line != null ? `(${this.line}:${this.column})` : '';
+                        return `${CtlValidationSeverity[this.severity]}: ${this.message} ${location}`.trim();
+                    }
+                });
+                break;
+        }
+    }
+    async resolveResource(reference, errors) {
+        const uri = reference.parsedUri;
+        const namespaceStr = uri.namespace_;
+        const doc = await this.repository.getDocumentAsync(namespaceStr);
+        if (!doc) {
+            errors.push(this.createError(CtlValidationErrorType.PackageNotFound, `Package not found: ${namespaceStr}`, reference));
+            return;
+        }
+        if (doc.body && doc.body[uri.resourceName]) {
+            reference.isResolved = true;
+        }
+        else {
+            const availableEntities = doc.body
+                ? Object.keys(doc.body).slice(0, 5)
+                : [];
+            errors.push(this.createError(CtlValidationErrorType.EntityNotFound, `Resource not found: ${uri.resourceName} in ${namespaceStr}`, reference, availableEntities.length > 0
+                ? `Available resources: ${availableEntities.join(', ')}`
+                : undefined));
+        }
+    }
+    async resolveDeepLink(reference, errors) {
+        const uri = reference.parsedUri;
+        const namespaceStr = uri.namespace_;
+        const doc = await this.repository.getDocumentAsync(namespaceStr);
+        if (!doc) {
+            errors.push(this.createError(CtlValidationErrorType.PackageNotFound, `Package not found: ${namespaceStr}`, reference));
+            return;
+        }
+        if (!doc.body || !doc.body[uri.resourceName]) {
+            errors.push(this.createError(CtlValidationErrorType.EntityNotFound, `Resource not found: ${uri.resourceName} in ${namespaceStr}`, reference));
+            return;
+        }
+        let current = doc.body[uri.resourceName];
+        let pathSoFar = uri.resourceName;
+        for (const segment of uri.path) {
+            if (current == null) {
+                errors.push(this.createError(CtlValidationErrorType.PathNotFound, `Path not found: ${pathSoFar}`, reference));
+                return;
+            }
+            if (segment.type_ === PathSegmentType.Property) {
+                const propertyName = segment.name;
+                pathSoFar += `.${propertyName}`;
+                const nextValue = navigateToProperty(current, propertyName);
+                if (nextValue === undefined) {
+                    const suggestion = getAvailablePropertiesSuggestion(current);
+                    errors.push(this.createError(CtlValidationErrorType.PathNotFound, `Path not found: ${pathSoFar}`, reference, suggestion));
+                    return;
+                }
+                current = nextValue;
+            }
+            else if (segment.type_ === PathSegmentType.Index) {
+                const index = segment.index;
+                pathSoFar += `[${index}]`;
+                const nextValue = navigateToIndex(current, index);
+                if (nextValue === undefined) {
+                    const suggestion = getCollectionSizeSuggestion(current);
+                    errors.push(this.createError(CtlValidationErrorType.IndexOutOfBounds, `Index out of bounds: ${pathSoFar}`, reference, suggestion));
+                    return;
+                }
+                current = nextValue;
+            }
+        }
+        reference.isResolved = true;
+        reference.resolvedValue = current;
+    }
+    createError(errorType, message, reference, suggestion) {
+        return {
+            errorType,
+            severity: CtlValidationSeverity.Error,
+            message,
+            reference,
+            line: reference.line,
+            column: reference.column,
+            suggestion,
+            toString() {
+                const location = this.line != null ? `(${this.line}:${this.column})` : '';
+                return `${CtlValidationSeverity[this.severity]}: ${this.message} ${location}`.trim();
+            }
+        };
+    }
+}
+function navigateToProperty(current, propertyName) {
+    if (current && typeof current === 'object' && !Array.isArray(current)) {
+        if (propertyName in current)
+            return current[propertyName];
+        const key = Object.keys(current).find((k) => k.toLowerCase() === propertyName.toLowerCase());
+        if (key)
+            return current[key];
+    }
+    return undefined;
+}
+function navigateToIndex(current, index) {
+    if (Array.isArray(current)) {
+        if (index >= 0 && index < current.length)
+            return current[index];
+    }
+    return undefined;
+}
+function getAvailablePropertiesSuggestion(current) {
+    if (current && typeof current === 'object' && !Array.isArray(current)) {
+        const keys = Object.keys(current).slice(0, 5);
+        if (keys.length > 0)
+            return `Available properties: ${keys.join(', ')}`;
+    }
+    return undefined;
+}
+function getCollectionSizeSuggestion(current) {
+    if (Array.isArray(current)) {
+        return current.length > 0
+            ? `Collection has ${current.length} items (valid indices: 0-${current.length - 1})`
+            : 'Collection is empty';
+    }
+    return undefined;
+}

package/dist/ctl/ResourceTypeClassifier.d.ts

@@ -0,0 +1,21 @@
+import type { SubjectCanon } from '@canon-protocol/types/object/canons/types';
+export declare class ResourceTypeClassifier {
+    static getTypeUri(resource: SubjectCanon): {
+        publisher: string;
+        package_: string;
+        name: string;
+    } | null;
+    static isCoreOntologyType(uri: {
+        publisher: string;
+        package_: string;
+    }): boolean;
+    static isClassType(resource: SubjectCanon): boolean;
+    static isDatatypeType(resource: SubjectCanon): boolean;
+    static isDatatypePropertyType(resource: SubjectCanon): boolean;
+    static isObjectPropertyType(resource: SubjectCanon): boolean;
+    static isAnnotationPropertyType(resource: SubjectCanon): boolean;
+    static isGenericPropertyType(resource: SubjectCanon): boolean;
+    static isAnyPropertyType(resource: SubjectCanon): boolean;
+    static isSchemaDefinitionType(resource: SubjectCanon): boolean;
+    static isInstanceOfKnownClass(resource: SubjectCanon, knownClassNames: Set<string>): boolean;
+}