@kanonak-protocol/types 1.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @kanonak-protocol/types
+
+TypeScript type definitions and interfaces for [Kanonak Protocol](https://kanonak.org).
+
+This package provides the type contracts used by `@kanonak-protocol/sdk` and `@kanonak-protocol/cli`. It is auto-generated from the C# source of truth and should not be edited manually.
+
+## Installation
+
+```bash
+npm install @kanonak-protocol/types
+```
+
+## What's included
+
+- **Document types** — `KanonakDocument`, `KanonakMetadata`, `Namespace`, `Import`, `Version`
+- **Object types** — `Kanonak`, `SubjectKanonak`, `EmbeddedKanonak`, `ReferenceKanonak`
+- **Statement types** — `IStatement`, `ScalarStatement`, `ReferenceStatement`, `EmbeddedStatement`
+- **Validation types** — `IDocumentValidationRule`, `IRepositoryValidationRule`
+- **Registry types** — OAuth, credential store, and publisher configuration interfaces
+- **CTL types** — Kanonak Template Language document and resolution types
+
+## Usage
+
+Most consumers should use `@kanonak-protocol/sdk` which re-exports these types along with implementations. Use this package directly only if you need the type definitions without the runtime code.
+
+```typescript
+import type { KanonakDocument, Import } from '@kanonak-protocol/types/document/models/types';
+import type { SubjectKanonak } from '@kanonak-protocol/types/object/kanonaks/types';
+```
+
+## License
+
+Apache-2.0

package/dist/ctl/models/enums.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Types of CTL validation errors.
+ */
+export declare enum CtlValidationErrorType {
+    /**
+     * The Kanonak URI could not be parsed.
+     */
+    InvalidUri = 0,
+    /**
+     * The referenced publisher does not exist.
+     */
+    PublisherNotFound = 1,
+    /**
+     * The referenced package does not exist.
+     */
+    PackageNotFound = 2,
+    /**
+     * The referenced package version does not exist.
+     */
+    VersionNotFound = 3,
+    /**
+     * The referenced entity does not exist in the package.
+     */
+    EntityNotFound = 4,
+    /**
+     * A path segment in a deep link could not be resolved.
+     */
+    PathNotFound = 5,
+    /**
+     * An array index in a deep link is out of bounds.
+     */
+    IndexOutOfBounds = 6,
+    /**
+     * The reference is ambiguous (multiple matches).
+     */
+    AmbiguousReference = 7,
+    /**
+     * General parse error in the CTL document.
+     */
+    ParseError = 8
+}
+/**
+ * Severity levels for CTL validation issues.
+ */
+export declare enum CtlValidationSeverity {
+    /**
+     * Error - the document is invalid.
+     */
+    Error = 0,
+    /**
+     * Warning - the document may have issues but is usable.
+     */
+    Warning = 1,
+    /**
+     * Information - advisory message.
+     */
+    Info = 2
+}

package/dist/ctl/models/enums.js

@@ -0,0 +1 @@
+var F=(u=>(u[u.InvalidUri=0]="InvalidUri",u[u.PublisherNotFound=1]="PublisherNotFound",u[u.PackageNotFound=2]="PackageNotFound",u[u.VersionNotFound=3]="VersionNotFound",u[u.EntityNotFound=4]="EntityNotFound",u[u.PathNotFound=5]="PathNotFound",u[u.IndexOutOfBounds=6]="IndexOutOfBounds",u[u.AmbiguousReference=7]="AmbiguousReference",u[u.ParseError=8]="ParseError",u))(F||{}),N=(s=>(s[s.Error=0]="Error",s[s.Warning=1]="Warning",s[s.Info=2]="Info",s))(N||{});export{F as CtlValidationErrorType,N as CtlValidationSeverity};

package/dist/ctl/models/types.d.ts

@@ -0,0 +1,169 @@
+import { CtlValidationErrorType, CtlValidationSeverity } from '../../ctl/models/enums';
+import { CtlKanonakUri } from '../../ctl/parsing/types';
+import { KanonakMetadata } from '../../document/models/types';
+import { SubjectKanonak } from '../../object/kanonaks/types';
+/**
+ * Represents a reference to a Kanonak entity found in a CTL document.     Corresponds to a markdown link: [DisplayText](kanonak://...)
+ */
+export interface KanonakReference {
+    /**
+     * The display text shown to the user (the link text).     Example: "Agent" in [Agent](kanonak://mycompany.com/models@1.0.0/Agent)
+     */
+    displayText: string;
+    /**
+     * The raw Kanonak URI string from the markdown link.     Example: "kanonak://mycompany.com/models@1.0.0/Agent"
+     */
+    rawUri: string;
+    /**
+     * The parsed Kanonak URI. Null if the URI failed to parse.
+     */
+    parsedUri?: CtlKanonakUri | null | undefined;
+    /**
+     * The character offset where this reference starts in the source markdown.
+     */
+    startOffset: number;
+    /**
+     * The character offset where this reference ends in the source markdown.
+     */
+    endOffset: number;
+    /**
+     * The line number (1-based) where this reference appears.
+     */
+    line: number;
+    /**
+     * The column number (1-based) where this reference starts.
+     */
+    column: number;
+    /**
+     * Whether this reference has been successfully resolved.
+     */
+    isResolved: boolean;
+    /**
+     * The resolved entity (for entity-level URIs). Null if not resolved or not an entity URI.
+     */
+    resolvedResource?: SubjectKanonak | null | undefined;
+    /**
+     * The resolved value for deep link URIs (could be a scalar, EmbeddedKanonak, etc.).     Null if not resolved or not a deep link URI.
+     */
+    resolvedValue?: any | null | undefined;
+    /**
+     * Error message if parsing or resolution failed.
+     */
+    error?: string | null | undefined;
+    /**
+     * The full markdown link text: [DisplayText](RawUri)
+     */
+    readonly fullMarkdownLink: string;
+}
+/**
+ * Represents a parsed CTL document (markdown with embedded Kanonak URI references).     Supports two modes:     - CTL Inline: No frontmatter, full kanonak:// URIs (for chat/responses)     - CTL Document: Kanonak YAML frontmatter with import aliases (for templates)
+ */
+export interface CtlDocument {
+    /**
+     * Kanonak metadata from YAML frontmatter (if present).     Contains publisher/package/version and imports with aliases.     Null for CTL Inline mode (no frontmatter).
+     */
+    metadata?: KanonakMetadata | null | undefined;
+    /**
+     * Whether this document has Kanonak frontmatter (CTL Document mode).
+     */
+    readonly hasFrontmatter: boolean;
+    /**
+     * The raw markdown content of the document (body only, without frontmatter).
+     */
+    rawMarkdown: string;
+    /**
+     * The length of the frontmatter section (including delimiters).     Used to calculate reference positions within the body.     Zero if no frontmatter.
+     */
+    frontmatterLength: number;
+    /**
+     * The file path of the document, if loaded from a file.
+     */
+    filePath?: string | null | undefined;
+    /**
+     * All Kanonak references found in the document.     URIs are fully resolved (alias links expanded to full kanonak:// URIs).
+     */
+    references: readonly KanonakReference[];
+    /**
+     * The number of references in the document.
+     */
+    readonly referenceCount: number;
+    /**
+     * Whether all references have been resolved successfully.
+     */
+    readonly allReferencesResolved: boolean;
+    /**
+     * References that failed to resolve.
+     */
+    readonly unresolvedReferences: Array<KanonakReference>;
+    /**
+     * References that have errors (parsing or resolution).
+     */
+    readonly errorReferences: Array<KanonakReference>;
+}
+/**
+ * A validation error or warning for a CTL document.
+ */
+export interface CtlValidationError {
+    /**
+     * The type of validation error.
+     */
+    errorType: CtlValidationErrorType;
+    /**
+     * The severity of the error.
+     */
+    severity: CtlValidationSeverity;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * The reference that caused the error, if applicable.
+     */
+    reference?: KanonakReference | null | undefined;
+    /**
+     * Line number (1-based) where the error occurred.
+     */
+    line?: number | null | undefined;
+    /**
+     * Column number (1-based) where the error occurred.
+     */
+    column?: number | null | undefined;
+    /**
+     * Suggestion for how to fix the error.
+     */
+    suggestion?: string | null | undefined;
+    toString(): string;
+}
+/**
+ * The result of validating a CTL document.
+ */
+export interface CtlValidationResult {
+    /**
+     * Whether the document is valid (all references resolved).
+     */
+    isValid: boolean;
+    /**
+     * The validated CTL document.
+     */
+    document: CtlDocument;
+    /**
+     * Validation errors (unresolved references, parse errors, etc.).
+     */
+    errors: readonly CtlValidationError[];
+    /**
+     * Validation warnings (non-fatal issues).
+     */
+    warnings: readonly CtlValidationError[];
+    /**
+     * Total number of references in the document.
+     */
+    readonly totalReferences: number;
+    /**
+     * Number of successfully resolved references.
+     */
+    readonly resolvedReferences: number;
+    /**
+     * Summary string for display.
+     */
+    readonly summary: string;
+}

package/dist/ctl/parsing/enums.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The type of Kanonak URI supported in CTL.     CTL only supports resource-level references (not package or publisher).
+ */
+export declare enum CtlKanonakUriType {
+    /**
+     * Publisher-level URI: kanonak://publisher     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    Publisher = 0,
+    /**
+     * Package-level URI without version: kanonak://publisher/package     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    Package = 1,
+    /**
+     * Package-level URI with version: kanonak://publisher/package@version     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    VersionedPackage = 2,
+    /**
+     * Resource-level URI: kanonak://publisher/package[@version]/resource
+     */
+    Resource = 3,
+    /**
+     * Deep link URI with path: kanonak://publisher/package[@version]/resource#path.to[0].field
+     */
+    DeepLink = 4
+}
+/**
+ * The type of a path segment.
+ */
+export declare enum PathSegmentType {
+    /**
+     * A property access: .propertyName
+     */
+    Property = 0,
+    /**
+     * An array index access: [0]
+     */
+    Index = 1
+}

package/dist/ctl/parsing/enums.js

@@ -0,0 +1 @@
+var s=(u=>(u[u.Publisher=0]="Publisher",u[u.Package=1]="Package",u[u.VersionedPackage=2]="VersionedPackage",u[u.Resource=3]="Resource",u[u.DeepLink=4]="DeepLink",u))(s||{}),x=(c=>(c[c.Property=0]="Property",c[c.Index=1]="Index",c))(x||{});export{s as CtlKanonakUriType,x as PathSegmentType};

package/dist/ctl/parsing/types.d.ts

@@ -0,0 +1,89 @@
+import { CtlDocument } from '../../ctl/models/types';
+import { CtlKanonakUriType, PathSegmentType } from '../../ctl/parsing/enums';
+import { Version } from '../../document/models/types';
+/**
+ * Represents a Kanonak URI used in CTL documents.     CTL supports resource-level references with optional deep linking:     - Resource: kanonak://publisher/package@version/resource     - Resource (latest): kanonak://publisher/package/resource     - Deep Link: kanonak://publisher/package@version/resource#path.to[0].field        Package and publisher-level URIs are NOT supported in CTL.     Use full resource URIs (kanonak://) or short URIs (kan://) resolved via imports.
+ */
+export interface CtlKanonakUri {
+    /**
+     * The URI scheme (always "kanonak").
+     */
+    readonly scheme: string;
+    /**
+     * The publisher/organization (e.g., "mycompany.com").
+     */
+    publisher: string;
+    /**
+     * The package name (e.g., "models"). Null for publisher-only URIs.
+     */
+    package_?: string | null | undefined;
+    /**
+     * The semantic version (e.g., "1.0.0"). Null for latest version.
+     */
+    version?: Version | null | undefined;
+    /**
+     * The resource name (e.g., "Agent"). Null for package-level URIs.
+     */
+    resourceName?: string | null | undefined;
+    /**
+     * The deep link path segments (e.g., ["address", "city"] or ["skills", "[0]", "name"]).     Empty for resource-level URIs without deep linking.
+     */
+    path: readonly PathSegment[];
+    /**
+     * The type of this URI based on its specificity.
+     */
+    readonly uriType: CtlKanonakUriType;
+    /**
+     * Returns the namespace string (publisher/package[@version]) if applicable.
+     */
+    readonly namespace_?: string | null | undefined;
+    /**
+     * The original raw URI string.
+     */
+    rawUri: string;
+    /**
+     * Converts the URI to its canonical string representation.
+     */
+    toString(): string;
+    equals(obj: any | null): boolean;
+    getHashCode(): number;
+}
+/**
+ * Parses CTL documents (markdown with embedded Kanonak URI references).     Supports two modes:     - CTL Inline: No frontmatter, full kanonak:// URIs (for chat/responses)     - CTL Document: Kanonak YAML frontmatter with import aliases (for templates)
+ */
+export interface CtlParser {
+    /**
+     * Parses a CTL markdown string into a CtlDocument.     Auto-detects mode based on frontmatter presence.
+     */
+    parse(content: string, filePath?: string | null): CtlDocument;
+    /**
+     * Parses a CTL document from a file.
+     */
+    parseFileAsync(filePath: string): Promise<CtlDocument>;
+}
+/**
+ * A segment in a deep link path.
+ */
+export interface PathSegment {
+    /**
+     * The type of path segment.
+     */
+    type_: PathSegmentType;
+    /**
+     * The property name (for Property segments).
+     */
+    name?: string | null | undefined;
+    /**
+     * The array index (for Index segments).
+     */
+    index?: number | null | undefined;
+    toString(): string;
+}
+/**
+ * Represents a resolved import with publisher, package, and version.
+ */
+export interface ResolvedImport {
+    publisher: string;
+    package_: string;
+    version: Version;
+}

package/dist/ctl/rendering/types.d.ts

@@ -0,0 +1,39 @@
+import { CtlDocument, CtlValidationResult } from '../../ctl/models/types';
+/**
+ * Renders CTL documents in various formats.     - Preview: Human-readable view with Kanonak references shown as display text     - Source: Original markdown (useful for display with syntax highlighting)
+ */
+export interface CtlPreviewRenderer {
+    /**
+     * Renders a CTL document as a preview (Kanonak links replaced with display text).
+     */
+    renderPreview(document: CtlDocument, options?: CtlRenderOptions | null): string;
+    /**
+     * Renders a CTL document as a summary showing all references.
+     */
+    renderReferenceSummary(document: CtlDocument): string;
+    /**
+     * Renders validation errors in a human-readable format.
+     */
+    renderValidationErrors(result: CtlValidationResult): string;
+    /**
+     * Exports a CTL document as JSON with resolved reference information.
+     */
+    exportAsJson(document: CtlDocument): string;
+}
+/**
+ * Options for rendering CTL documents.
+ */
+export interface CtlRenderOptions {
+    /**
+     * Whether to indicate Kanonak references with markers.
+     */
+    indicateReferences: boolean;
+    /**
+     * Marker format for resolved references. Use {text} as placeholder.     Default: "«{text}»"
+     */
+    resolvedMarker?: string | null | undefined;
+    /**
+     * Marker format for unresolved references. Use {text} as placeholder.     Default: "⚠{text}⚠"
+     */
+    unresolvedMarker?: string | null | undefined;
+}

package/dist/ctl/resolution/enums.d.ts

@@ -0,0 +1,34 @@
+export declare enum EntityTier {
+    Direct = 0,
+    Inherited = 1,
+    Foundation = 2
+}
+/**
+ * Semantic type classification for resolved entities.
+ */
+export declare enum ResolvedResourceType {
+    /**
+     * An rdfs:Class or owl:Class definition.
+     */
+    Class = 0,
+    /**
+     * An owl:AnnotationProperty definition.
+     */
+    AnnotationProperty = 1,
+    /**
+     * An owl:DatatypeProperty definition.
+     */
+    DatatypeProperty = 2,
+    /**
+     * An owl:ObjectProperty definition.
+     */
+    ObjectProperty = 3,
+    /**
+     * An instance of a class (not a schema definition).
+     */
+    Instance = 4,
+    /**
+     * Unknown or unclassifiable entity type.
+     */
+    Other = 5
+}

package/dist/ctl/resolution/enums.js

@@ -0,0 +1 @@
+var t=(n=>(n[n.Direct=0]="Direct",n[n.Inherited=1]="Inherited",n[n.Foundation=2]="Foundation",n))(t||{}),P=(a=>(a[a.Class=0]="Class",a[a.AnnotationProperty=1]="AnnotationProperty",a[a.DatatypeProperty=2]="DatatypeProperty",a[a.ObjectProperty=3]="ObjectProperty",a[a.Instance=4]="Instance",a[a.Other=5]="Other",a))(P||{});export{t as EntityTier,P as ResolvedResourceType};

package/dist/ctl/resolution/types.d.ts

@@ -0,0 +1,156 @@
+import { CtlDocument } from '../../ctl/models/types';
+import { ResolvedResourceType } from '../../ctl/resolution/enums';
+import { SubjectKanonak } from '../../object/kanonaks/types';
+/**
+ * Resolves the complete entity graph for a CTL document.     Recursively resolves all referenced entities and their dependencies,     organizing them into tiers by importance.        Uses ResourceResolver from Kanonak.Object for proper transitive alias resolution.
+ */
+export interface CtlGraphResolver {
+    /**
+     * Resolves the complete entity graph for a CTL document.
+     */
+    resolveAsync(document: CtlDocument, maxDepth?: number): Promise<ResolvedResourceGraph>;
+}
+/**
+ * A property of a resolved Class entity.
+ */
+export interface ResolvedProperty {
+    /**
+     * The property name.
+     */
+    name: string;
+    /**
+     * The property's range types (supports RDF union types like range: [string, anyURI]).
+     */
+    rangeTypes: Array<string>;
+    /**
+     * The property's domain types (supports multiple domains like domain: [ClassA, ClassB]).
+     */
+    domains: Array<string>;
+    /**
+     * Convenience property for single range type (first in list, or "unknown" if empty).
+     */
+    readonly rangeType: string;
+    /**
+     * Whether this is an object property (reference to another entity).
+     */
+    isObjectProperty: boolean;
+    /**
+     * Whether this property is a collection.
+     */
+    isCollection: boolean;
+    /**
+     * The rdfs:comment or description of this property.
+     */
+    comment?: string | null | undefined;
+}
+/**
+ * A resolved Kanonak resource with metadata for documentation rendering.
+ */
+export interface ResolvedResource {
+    /**
+     * The resource name (e.g., "Farm", "tableName").
+     */
+    name: string;
+    /**
+     * The full Kanonak URI (e.g., "kanonak://spec.farm/models.farming@1.1.0/Farm").
+     */
+    kanonakUri: string;
+    /**
+     * The parsed SubjectKanonak resource (contains all statements/properties).
+     */
+    resource: SubjectKanonak;
+    /**
+     * The semantic type of this resource.
+     */
+    resourceType: ResolvedResourceType;
+    /**
+     * Parent class name (for Class entities with subClassOf).
+     */
+    parentClass?: string | null | undefined;
+    /**
+     * Multiple parent classes (for Class entities with multiple inheritance).
+     */
+    parentClasses: Array<string>;
+    /**
+     * The rdfs:comment or description of this entity.
+     */
+    comment?: string | null | undefined;
+    /**
+     * Properties defined on this entity (for Class entities).
+     */
+    properties: Array<ResolvedProperty>;
+    /**
+     * The namespace this entity belongs to.
+     */
+    namespace_: string;
+    /**
+     * The depth at which this entity was resolved (0 = direct reference).
+     */
+    resolutionDepth: number;
+    /**
+     * For Instance resources, the type/class this is an instance of.
+     */
+    instanceOf_?: string | null | undefined;
+}
+/**
+ * Represents a fully resolved entity graph from a CTL document.     Entities are organized into tiers by importance/proximity to the source document.
+ */
+export interface ResolvedResourceGraph {
+    /**
+     * The source file path (if available).
+     */
+    sourceFile?: string | null | undefined;
+    /**
+     * The original markdown content of the CTL document.
+     */
+    originalContent: string;
+    /**
+     * The title extracted from the first H1 heading, if present.
+     */
+    title?: string | null | undefined;
+    /**
+     * Direct references - entities explicitly referenced in the template via kan:// links.     These are the most important and appear first in output.
+     */
+    directReferences: Array<ResolvedResource>;
+    /**
+     * Inherited references - parent classes (subClassOf), property ranges, etc.     These are referenced by direct entities but not explicitly in the template.
+     */
+    inheritedReferences: Array<ResolvedResource>;
+    /**
+     * Foundation types - core ontology types (rdf:Class, rdfs:Resource, owl:Thing, etc.).     These form the base of the type hierarchy.
+     */
+    foundationTypes: Array<ResolvedResource>;
+    /**
+     * Total number of resolved resources across all tiers.
+     */
+    readonly totalResourceCount: number;
+    /**
+     * All resolved resources across all tiers (for iteration).
+     */
+    readonly allResources: Array<ResolvedResource>;
+    /**
+     * Maximum depth reached during resolution.
+     */
+    maxDepthReached: number;
+    /**
+     * Whether resolution was truncated due to depth limit.
+     */
+    wasTruncated: boolean;
+    /**
+     * Resources that failed to resolve (for diagnostic purposes).
+     */
+    unresolvedResources: Array<UnresolvedResource>;
+}
+/**
+ * An entity that failed to resolve.
+ */
+export interface UnresolvedResource {
+    /**
+     * The entity name or URI that failed to resolve.
+     */
+    reference: string;
+    /**
+     * The reason for failure.
+     */
+    reason: string;
+}

package/dist/ctl/validation/types.d.ts

@@ -0,0 +1,10 @@
+import { CtlDocument, CtlValidationResult } from '../../ctl/models/types';
+/**
+ * Validates CTL documents by resolving all Kanonak URI references.     CTL only supports entity-level references (Entity and DeepLink URIs).     Package and publisher-level URIs are not supported.
+ */
+export interface CtlValidator {
+    /**
+     * Validates a CTL document by resolving all Kanonak URI references.
+     */
+    validateAsync(document: CtlDocument): Promise<CtlValidationResult>;
+}

package/dist/document/constants/types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Centralized constants for core Kanonak Protocol package names and identifiers.     All package name references should use these constants for maintainability.
+ */
+export interface CorePackageConstants {
+}

package/dist/document/filtering/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Interface for filtering files based on .gitignore rules
+ */
+export interface IGitIgnoreFilter {
+    /**
+     * Checks if a file path should be ignored based on gitignore rules
+     */
+    shouldIgnore(absolutePath: string): boolean;
+    /**
+     * Checks if a directory path should be ignored based on gitignore rules.     Used to skip entire directory trees before traversing them.
+     */
+    shouldIgnoreDirectory(absoluteDirectoryPath: string): boolean;
+}