cwtools-shared 0.1.0

package/dist/knowledge/rules.d.ts

@@ -0,0 +1,162 @@
+import type { HostServices } from '../host/hostServices';
+import type { SharedToolResult } from '../tools/schema';
+export interface RuleInfo {
+    name: string;
+    description: string;
+    scopes: string[];
+    syntax: string;
+    category?: QueryRulesArgs['category'];
+    sourceFile?: string;
+    sourceLine?: number;
+    hardFacts?: RuleHardFacts;
+    semanticHints?: RuleSemanticHint[];
+}
+export interface QueryRulesArgs {
+    category: 'trigger' | 'effect' | 'scope_change' | 'modifier';
+    name?: string;
+    scope?: string;
+}
+export interface QueryRulesResult {
+    rules: RuleInfo[];
+    totalCount: number;
+    truncated: boolean;
+    source: 'cwtools-node-rules';
+    warnings?: string[];
+    /**
+     * Cache lifecycle metadata (plan §7.4): monotonic per-host reload counter
+     * plus a content hash of the rule files, so evidence consumers can detect
+     * stale rule data. `generation` 0 means the memoization lifecycle is
+     * unavailable (no fs access to compute a freshness signature).
+     */
+    rulesGeneration?: number;
+    /** sha256 (16 hex chars) over the rule file contents; see computeRulesContentHash. */
+    rulesContentHash?: string;
+}
+export interface QueryCwtSchemaArgs {
+    target?: string;
+    file?: string;
+    directory?: string;
+    name?: string;
+    includeContent?: boolean;
+    limit?: number;
+}
+export interface CwtSchemaMatch {
+    ruleFile: string;
+    relativeRuleFile: string;
+    sourceRoot: string;
+    score: number;
+    matchedBy: string[];
+    snippet?: string;
+    startLine?: number;
+    endLine?: number;
+    truncated?: boolean;
+}
+export interface CwtSchemaEntitySummary {
+    name: string;
+    path?: string;
+    nameField?: string;
+    ruleFile: string;
+    relativeRuleFile: string;
+    sourceRoot: string;
+    line: number;
+    subtypes: string[];
+    typeKeyFilters?: string[];
+    schemaKeys: string[];
+    graphRelatedTypes?: string[];
+    shaderReferences?: Array<{
+        argumentPath: string;
+        referenceKind: 'shader_effect' | 'shader_file';
+        dynamicValuePolicy: 'allow_expression' | 'literal_or_parameter';
+        pathPrefix?: string;
+        extension?: string;
+    }>;
+    matchedBy: string[];
+    snippet?: string;
+    truncated?: boolean;
+}
+export interface QueryCwtSchemaResult {
+    status: 'ready' | 'not_found';
+    target?: string;
+    normalizedTarget?: string;
+    name?: string;
+    rulesRoots: string[];
+    matches: CwtSchemaMatch[];
+    entities: CwtSchemaEntitySummary[];
+    entityCount: number;
+    warnings?: string[];
+    _hint?: string;
+}
+export interface SearchRuleCapabilitiesArgs {
+    intent?: string;
+    category?: QueryRulesArgs['category'] | 'all';
+    currentScope?: string;
+    desiredPushScope?: string;
+    limit?: number;
+}
+export interface RuleCapabilityCandidate {
+    rule: RuleInfo;
+    score: number;
+    reasons: string[];
+}
+export interface SearchRuleCapabilitiesResult {
+    status: 'ready';
+    candidates: RuleCapabilityCandidate[];
+    totalConsidered: number;
+    source: 'cwtools-node-rules';
+    warnings?: string[];
+    /** Cache lifecycle metadata (plan §7.4); see QueryRulesResult. */
+    rulesGeneration?: number;
+    rulesContentHash?: string;
+}
+export interface ExplainScopeArgs {
+    scope: string;
+}
+export interface ExplainScopeResult {
+    status: 'ready' | 'not_found';
+    scope: string;
+    canonicalName?: string;
+    aliases?: string[];
+    isSubscopeOf?: string[];
+    description?: string;
+    source?: {
+        file: string;
+        line: number;
+    };
+    semanticHints?: RuleSemanticHint[];
+    suggestions?: string[];
+    /** Cache lifecycle metadata (plan §7.4); see QueryRulesResult. */
+    rulesGeneration?: number;
+    rulesContentHash?: string;
+}
+export interface RuleHardFacts {
+    category: QueryRulesArgs['category'];
+    supportedScopes?: string[];
+    pushScope?: string;
+    typeKeyFilter?: string;
+    valueReferences?: CwtRuleValueReference[];
+    syntax?: string;
+    cwtSource?: {
+        file: string;
+        line: number;
+    };
+}
+export interface CwtRuleValueReference {
+    argumentPath: string;
+    access: 'value' | 'value_set' | 'scope' | 'type';
+    typeName: string;
+}
+export interface RuleSemanticHint {
+    text: string;
+    source: 'trigger_docs.log' | 'scopes.cwt' | 'cwt-comment' | 'modifiers.log';
+    file?: string;
+    line?: number;
+    confidence: 'hint';
+}
+export declare function queryRulesWithHost(host: HostServices, args: QueryRulesArgs): Promise<SharedToolResult<QueryRulesResult>>;
+export declare function queryCwtSchemaWithHost(host: HostServices, args?: QueryCwtSchemaArgs): Promise<SharedToolResult<QueryCwtSchemaResult>>;
+export declare function searchRuleCapabilitiesWithHost(host: HostServices, args?: SearchRuleCapabilitiesArgs): Promise<SharedToolResult<SearchRuleCapabilitiesResult>>;
+export declare function explainScopeWithHost(host: HostServices, args: ExplainScopeArgs): Promise<SharedToolResult<ExplainScopeResult>>;
+export interface CwtRulesCacheMeta {
+    generation: number;
+    contentHash: string;
+}