cwtools-shared 0.2.1 → 0.2.3

package/dist/knowledge/rules.d.ts

@@ -147,7 +147,7 @@ export interface CwtRuleValueReference {
 }
 export interface RuleSemanticHint {
     text: string;
-    source: 'trigger_docs.log' | 'scopes.cwt' | 'cwt-comment' | 'modifiers.log';
+    source: 'trigger_docs.log' | 'scopes.cwt' | 'links.cwt' | 'cwt-comment' | 'modifiers.log';
     file?: string;
     line?: number;
     confidence: 'hint';

package/dist/knowledge/rules.js

@@ -49,9 +49,15 @@ async function queryRulesWithHost(host, args) {
             : args.category === 'modifier'
                 ? cache.modifiers
                 : cache.scopeChanges;
+    const dottedScopeChain = args.name && args.category === 'scope_change'
+        ? buildDottedScopeChainRule(args.name, args.scope, cache.scopeChanges)
+        : undefined;
     if (args.name) {
-        const needle = args.name.toLowerCase();
-        const filtered = rules.filter(rule => rule.name.toLowerCase().includes(needle));
+        const needle = normalizeRuleNameQuery(args.name, args.category);
+        const filtered = rules
+            .filter(rule => rule.name.toLowerCase().includes(needle))
+            .sort((a, b) => scoreRuleNameMatch(a.name, needle) - scoreRuleNameMatch(b.name, needle)
+            || a.name.localeCompare(b.name));
         if (filtered.length === 0 && rules.length > 0) {
             rules = rules
                 .map(rule => ({ rule, score: levenshtein(needle, rule.name.toLowerCase()) }))
@@ -66,6 +72,12 @@ async function queryRulesWithHost(host, args) {
             rules = filtered;
         }
     }
+    if (dottedScopeChain) {
+        rules = [
+            dottedScopeChain,
+            ...rules.filter(rule => rule.name !== dottedScopeChain.name),
+        ];
+    }
     if (args.scope) {
         const scope = args.scope.toLowerCase();
         rules = rules.filter(rule => rule.scopes.length === 0
@@ -322,13 +334,45 @@ function normalizeCwtSchemaTarget(host, value) {
 }
 async function findCwtSchemaFiles(host, root, maxFiles) {
     if (host.rules?.listCwtFiles) {
-        return (await host.rules.listCwtFiles(root, { limit: maxFiles })).slice(0, maxFiles);
+        return (await host.rules.listCwtFiles(root, { limit: maxFiles }))
+            .slice(0, maxFiles)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    if (fs.existsSync(root)) {
+        const results = [];
+        const ignoredDirs = new Set(['.git', 'node_modules', 'logs', 'config']);
+        const walkDisk = (dir, depth) => {
+            if (results.length >= maxFiles || depth > 8)
+                return;
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                if (results.length >= maxFiles)
+                    break;
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (!ignoredDirs.has(entry.name))
+                        walkDisk(fullPath, depth + 1);
+                }
+                else if (entry.isFile() && entry.name.toLowerCase().endsWith('.cwt')) {
+                    results.push(fullPath);
+                }
+            }
+        };
+        walkDisk(root, 0);
+        return results.sort((a, b) => a.localeCompare(b));
     }
     const rootRelative = workspaceRelativePath(host.workspaceRoot, root);
     if (!rootRelative)
         return [];
     const results = [];
-    const ignoredDirs = new Set(['.git', 'node_modules', 'logs']);
+    const ignoredDirs = new Set(['.git', 'node_modules', 'logs', 'config']);
     const walk = async (relativeDir, depth) => {
         if (results.length >= maxFiles || depth > 8)
             return;
@@ -339,6 +383,7 @@ async function findCwtSchemaFiles(host, root, maxFiles) {
         catch {
             return;
         }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
         for (const entry of entries) {
             if (results.length >= maxFiles)
                 break;
@@ -354,7 +399,16 @@ async function findCwtSchemaFiles(host, root, maxFiles) {
         }
     };
     await walk(rootRelative, 0);
-    return results;
+    return results.sort((a, b) => a.localeCompare(b));
+}
+async function collectCwtRuleSourceFiles(host, root, includeMissingLogs) {
+    const files = await findCwtSchemaFiles(host, root, CWT_RULE_FILE_SCAN_LIMIT);
+    for (const relativeLog of CWT_RULE_LOG_CANDIDATES) {
+        const fullPath = path.join(root, relativeLog);
+        if (includeMissingLogs || fs.existsSync(fullPath))
+            files.push(fullPath);
+    }
+    return Array.from(new Set(files)).sort((a, b) => a.localeCompare(b));
 }
 function workspaceRelativePath(workspaceRoot, fullPath) {
     const relative = path.relative(workspaceRoot, fullPath);
@@ -715,27 +769,18 @@ function scoreCwtSchemaEntity(summary, normalizedTarget, name) {
 //
 // loadCwtRules used to re-read and re-parse every rule file on each query.
 // The memo keeps one parsed CwtRuleCache per host identity, invalidated by an
-// mtime/size signature over a bounded candidate file set (12 files per config
-// root). `generation` is a per-host monotonic reload counter; `contentHash` is
-// sha256 (16 hex chars) over the length-prefixed concatenation of every
-// candidate rule file's content — the same algorithm the extension-side
+// mtime/size signature over every .cwt file under the active config roots plus
+// the docs/modifier logs. `generation` is a per-host monotonic reload counter;
+// `contentHash` is sha256 (16 hex chars) over the length-prefixed concatenation
+// of the same files' content — the same algorithm the extension-side
 // LspToolHandler uses, so both ends describe rule revisions with the same
 // hash semantics. The cache is process-local and bounded
 // (CWT_RULES_MEMO_MAX_ENTRIES).
-const CWT_RULE_FILE_CANDIDATES = [
-    'scopes.cwt',
+const CWT_RULE_LOG_CANDIDATES = [
     path.join('logs', 'trigger_docs.log'),
     path.join('logs', 'modifiers.log'),
-    'triggers.cwt',
-    'trigger.cwt',
-    path.join('generated', 'triggers.generated.cwt'),
-    'effects.cwt',
-    'effect.cwt',
-    path.join('generated', 'effects.generated.cwt'),
-    'modifier.cwt',
-    'scope_changes.cwt',
-    path.join('generated', 'scope_changes.generated.cwt'),
 ];
+const CWT_RULE_FILE_SCAN_LIMIT = 5000;
 const CWT_RULES_MEMO_MAX_ENTRIES = 8;
 /**
  * When no candidate rule file exists on disk, the mtime signature cannot
@@ -744,12 +789,11 @@ const CWT_RULES_MEMO_MAX_ENTRIES = 8;
  */
 const CWT_RULES_MEMO_REFRESH_MS = 30000;
 const cwtRulesMemo = new Map();
-function computeRulesSignature(configPaths) {
+async function computeRulesSignature(host, configPaths) {
     const parts = [];
     let sawDiskFiles = false;
     for (const configPath of configPaths) {
-        for (const file of CWT_RULE_FILE_CANDIDATES) {
-            const fullPath = path.join(configPath, file);
+        for (const fullPath of await collectCwtRuleSourceFiles(host, configPath, true)) {
             try {
                 const stat = fs.statSync(fullPath);
                 parts.push(`${fullPath}:${stat.mtimeMs}:${stat.size}`);
@@ -772,8 +816,8 @@ function computeRulesSignature(configPaths) {
 async function computeRulesContentHash(host, configPaths) {
     const hash = crypto.createHash('sha256');
     for (const configPath of configPaths) {
-        for (const file of CWT_RULE_FILE_CANDIDATES) {
-            const read = await readRulesTextFile(host, path.join(configPath, file)).catch(() => ({ exists: false, content: '', hasBom: false }));
+        for (const file of await collectCwtRuleSourceFiles(host, configPath, true)) {
+            const read = await readRulesTextFile(host, file).catch(() => ({ exists: false, content: '', hasBom: false }));
             if (!read.exists)
                 continue;
             hash.update(`${read.content.length}:`);
@@ -788,7 +832,7 @@ function cwtRulesHostKey(host) {
 async function loadCwtRulesMemoized(host) {
     const configPaths = await resolveRulesConfigPaths(host);
     const hostKey = cwtRulesHostKey(host);
-    const { signature, sawDiskFiles } = computeRulesSignature(configPaths);
+    const { signature, sawDiskFiles } = await computeRulesSignature(host, configPaths);
     const memo = cwtRulesMemo.get(hostKey);
     if (memo && memo.signature === signature && (memo.sawDiskFiles || host.now() - memo.computedAt < CWT_RULES_MEMO_REFRESH_MS)) {
         return { cache: memo.cache, meta: { generation: memo.generation, contentHash: memo.contentHash } };
@@ -824,10 +868,25 @@ async function loadCwtRulesFromPaths(host, configPaths) {
         const scopes = scopesRead.exists
             ? parseScopesFile(scopesRead.content, path.join(configPath, 'scopes.cwt'))
             : new Map();
-        const triggers = await readRuleFiles(host, configPath, ['triggers.cwt', 'trigger.cwt', path.join('generated', 'triggers.generated.cwt')], 'trigger', docs, scopes);
-        const effects = await readRuleFiles(host, configPath, ['effects.cwt', 'effect.cwt', path.join('generated', 'effects.generated.cwt')], 'effect', docs, scopes);
-        const scopeChanges = await readRuleFiles(host, configPath, ['scope_changes.cwt', path.join('generated', 'scope_changes.generated.cwt')], 'scope_change', docs, scopes);
-        const modifierAliases = await readRuleFiles(host, configPath, ['modifier.cwt'], 'modifier', docs, scopes);
+        const triggers = [];
+        const effects = [];
+        const scopeChanges = [];
+        const modifierAliases = [];
+        for (const file of await findCwtSchemaFiles(host, configPath, CWT_RULE_FILE_SCAN_LIMIT)) {
+            const relativeFile = path.relative(configPath, file).replace(/\\/g, '/');
+            const parsed = await readRulesFile(host, file, scopeChangeFileCategoryOverride(relativeFile), docs, scopes);
+            for (const rule of parsed) {
+                if (rule.category === 'trigger')
+                    triggers.push(rule);
+                else if (rule.category === 'effect')
+                    effects.push(rule);
+                else if (rule.category === 'modifier')
+                    modifierAliases.push(rule);
+                else
+                    scopeChanges.push(rule);
+            }
+            scopeChanges.push(...await readLinksFile(host, file, scopes));
+        }
         const modifierLog = await readModifiersLog(host, path.join(configPath, 'logs', 'modifiers.log'));
         const modifiers = [...modifierAliases];
         const modifierNames = new Set(modifiers.map(rule => rule.name.toLowerCase()));
@@ -925,6 +984,12 @@ async function readRulesFile(host, filePath, category, docs, scopes) {
         return [];
     return parseCwtFile(read.content, filePath, category, docs, scopes);
 }
+function scopeChangeFileCategoryOverride(relativeRuleFile) {
+    const base = path.posix.basename(relativeRuleFile.replace(/\\/g, '/')).toLowerCase();
+    return base === 'scope_changes.cwt' || base === 'scope_changes.generated.cwt' || base === 'scope_change.cwt'
+        ? 'scope_change'
+        : undefined;
+}
 async function readModifiersLog(host, filePath) {
     const read = await readRulesTextFile(host, filePath).catch(() => ({ exists: false, content: '', hasBom: false }));
     if (!read.exists)
@@ -1035,7 +1100,7 @@ function parseScopesFile(content, filePath) {
     }
     return scopes;
 }
-function parseCwtFile(content, filePath, category, docs, scopes) {
+function parseCwtFile(content, filePath, categoryOverride, docs, scopes) {
     const results = [];
     let currentScopes = [];
     let currentSupportedScopes = [];
@@ -1080,9 +1145,11 @@ function parseCwtFile(content, filePath, category, docs, scopes) {
                 currentDesc = comment;
             continue;
         }
-        const nameMatch = line.match(/^alias\[(?:trigger|effect|modifier):([^\]]+)\]\s*=\s*(.*)/);
-        if (nameMatch?.[1]) {
-            const name = nameMatch[1];
+        const nameMatch = line.match(/^alias\[(trigger|effect|modifier):([^\]]+)\]\s*=\s*(.*)/);
+        if (nameMatch?.[1] && nameMatch[2]) {
+            const aliasKind = nameMatch[1];
+            const category = categoryOverride ?? aliasKind;
+            const name = nameMatch[2];
             const doc = docs.get(name);
             const cwtBlockText = collectCwtBlockText(lines, i);
             const scopesForRule = doc?.scopes.length
@@ -1090,7 +1157,7 @@ function parseCwtFile(content, filePath, category, docs, scopes) {
                 : currentSupportedScopes.length
                     ? currentSupportedScopes
                     : currentScopes;
-            const syntax = doc?.syntax || normalizeInlineSyntax(name, nameMatch[2] ?? '');
+            const syntax = doc?.syntax || normalizeInlineSyntax(name, nameMatch[3] ?? '');
             const description = doc?.description || currentDesc;
             const semanticHints = buildSemanticHints({
                 description,
@@ -1134,6 +1201,92 @@ function parseCwtFile(content, filePath, category, docs, scopes) {
     }
     return results;
 }
+async function readLinksFile(host, filePath, scopes) {
+    const read = await readRulesTextFile(host, filePath).catch(() => ({ exists: false, content: '', hasBom: false }));
+    if (!read.exists || !/^\s*links\s*=\s*\{/im.test(read.content))
+        return [];
+    return parseLinksCwtFile(read.content, filePath, scopes);
+}
+function parseLinksCwtFile(content, filePath, scopes) {
+    const results = [];
+    const lines = content.split(/\r?\n/);
+    let inLinks = false;
+    let depth = 0;
+    let current;
+    for (let i = 0; i < lines.length; i++) {
+        const rawLine = lines[i] ?? '';
+        const line = stripCwtLineComment(rawLine).trim();
+        if (!inLinks) {
+            if (/^links\s*=\s*\{/.test(line)) {
+                inLinks = true;
+                depth = countBraceDelta(line);
+            }
+            continue;
+        }
+        if (!current && depth === 1) {
+            const linkMatch = line.match(/^([A-Za-z_][\w.-]*)\s*=\s*\{\s*$/);
+            if (linkMatch?.[1])
+                current = { name: linkMatch[1], line: i + 1, inputScopes: [] };
+        }
+        else if (current) {
+            const inputMatch = line.match(/^input_scopes\s*=\s*(.*)$/i);
+            if (inputMatch?.[1])
+                current.inputScopes = splitRuleValueList(inputMatch[1]).map(normalizeScopeName);
+            const outputMatch = line.match(/^output_scope\s*=\s*(.*)$/i);
+            if (outputMatch?.[1]) {
+                const outputScope = stripRuleValueBraces(outputMatch[1]).split(/\s+/)[0];
+                if (outputScope)
+                    current.outputScope = normalizeScopeName(outputScope);
+            }
+        }
+        depth += countBraceDelta(line);
+        if (current && depth <= 1) {
+            if (current.outputScope) {
+                const inputScopes = current.inputScopes.length ? current.inputScopes : ['all'];
+                const syntax = `${current.name} = scope link (${inputScopes.join(' | ')} -> ${current.outputScope})`;
+                const linkHint = {
+                    text: `Legal scope link '${current.name}' accepts input scopes { ${inputScopes.join(' ')} } and outputs '${current.outputScope}'. Context pointers such as from/prev/root/this select the current input scope; they are not fixed object fields.`,
+                    source: 'links.cwt',
+                    file: filePath,
+                    line: current.line,
+                    confidence: 'hint',
+                };
+                const scopeHints = buildSemanticHints({
+                    description: '',
+                    cwtDescription: '',
+                    scopes,
+                    relatedScopeNames: [...inputScopes, current.outputScope],
+                    cwtFile: filePath,
+                    cwtLine: current.line,
+                });
+                results.push({
+                    name: current.name,
+                    description: `Legal scope link from { ${inputScopes.join(' ')} } to ${current.outputScope}.`,
+                    scopes: inputScopes,
+                    syntax,
+                    category: 'scope_change',
+                    sourceFile: filePath,
+                    sourceLine: current.line,
+                    hardFacts: {
+                        category: 'scope_change',
+                        supportedScopes: inputScopes,
+                        pushScope: current.outputScope,
+                        valueReferences: [],
+                        syntax,
+                        cwtSource: { file: filePath, line: current.line },
+                    },
+                    semanticHints: [linkHint, ...scopeHints].slice(0, 8),
+                });
+            }
+            current = undefined;
+        }
+        if (inLinks && depth <= 0) {
+            inLinks = false;
+            current = undefined;
+        }
+    }
+    return results;
+}
 function buildSemanticHints(args) {
     const hints = [];
     const seen = new Set();
@@ -1287,7 +1440,12 @@ function expandIntentTokens(intent) {
         [/触发器|觸發器/g, ['trigger']],
         [/效果|效应|效應/g, ['effect']],
     ];
-    const expanded = [...direct];
+    const expanded = [];
+    for (const token of direct) {
+        expanded.push(token);
+        if (/[.:]/.test(token))
+            expanded.push(...token.split(/[.:]+/).filter(Boolean));
+    }
     for (const [pattern, tokens] of synonyms) {
         pattern.lastIndex = 0;
         if (pattern.test(intent))
@@ -1363,6 +1521,98 @@ function splitRuleValueList(value) {
 function stripRuleValueBraces(value) {
     return value.replace(/^\{\s*/, '').replace(/\s*\}$/, '').trim();
 }
+function normalizeRuleNameQuery(name, category) {
+    const lowered = name.trim().toLowerCase();
+    if (category !== 'scope_change' || !lowered.includes('.'))
+        return lowered;
+    const parts = lowered.split('.').map(part => part.trim()).filter(Boolean);
+    return parts[parts.length - 1] ?? lowered;
+}
+function buildDottedScopeChainRule(query, contextScope, scopeChanges) {
+    const rawParts = query.trim().split('.').map(normalizeScopeName).filter(Boolean);
+    if (rawParts.length < 2)
+        return undefined;
+    const contextPointers = new Set(['from', 'prev', 'root', 'this']);
+    const first = rawParts[0];
+    const startsWithPointer = contextPointers.has(first);
+    const initialScope = startsWithPointer ? contextScope?.trim().toLowerCase() : first;
+    const linkNames = rawParts.slice(1);
+    if (!initialScope || linkNames.length === 0)
+        return undefined;
+    const hops = [];
+    let currentScope = initialScope;
+    for (const linkName of linkNames) {
+        const link = scopeChanges.find(rule => rule.name.toLowerCase() === linkName
+            && !!rule.hardFacts?.pushScope
+            && scopeListContains(rule.hardFacts.supportedScopes ?? rule.scopes, currentScope));
+        const outputScope = link?.hardFacts?.pushScope?.trim().toLowerCase();
+        if (!link || !outputScope)
+            return undefined;
+        hops.push({ link, inputScope: currentScope, outputScope });
+        currentScope = outputScope;
+    }
+    if (hops.length === 0)
+        return undefined;
+    const normalizedQuery = rawParts.join('.');
+    const syntax = `${normalizedQuery} = { ... }`;
+    const source = hops[0].link;
+    const hopText = hops.map(hop => `${hop.inputScope}.${hop.link.name} -> ${hop.outputScope}`).join('; ');
+    const linkHints = hops.map((hop) => ({
+        text: `Dotted scope chain hop '${hop.inputScope}.${hop.link.name}' is legal because links.cwt declares '${hop.link.name}' with input scope '${hop.inputScope}' and output scope '${hop.outputScope}'.`,
+        source: 'links.cwt',
+        file: hop.link.sourceFile,
+        line: hop.link.sourceLine,
+        confidence: 'hint',
+    }));
+    return {
+        name: normalizedQuery,
+        description: `Legal dotted scope chain from ${initialScope} to ${currentScope}. Hops: ${hopText}.`,
+        scopes: [initialScope],
+        syntax,
+        category: 'scope_change',
+        sourceFile: source.sourceFile,
+        sourceLine: source.sourceLine,
+        hardFacts: {
+            category: 'scope_change',
+            supportedScopes: [initialScope],
+            pushScope: currentScope,
+            valueReferences: [],
+            syntax,
+            cwtSource: source.sourceFile && source.sourceLine
+                ? { file: source.sourceFile, line: source.sourceLine }
+                : undefined,
+        },
+        semanticHints: linkHints.slice(0, 8),
+    };
+}
+function scopeListContains(scopes, scope) {
+    const lowerScope = scope.toLowerCase();
+    return scopes.some(candidate => {
+        const lower = candidate.toLowerCase();
+        return lower === lowerScope || lower === 'all' || lower === 'any';
+    });
+}
+function scoreRuleNameMatch(name, needle) {
+    const lower = name.toLowerCase();
+    if (lower === needle)
+        return 0;
+    if (lower.startsWith(needle))
+        return 1;
+    return 2;
+}
+function normalizeScopeName(scope) {
+    return scope.replace(/^["']|["']$/g, '').trim().toLowerCase();
+}
+function countBraceDelta(line) {
+    let delta = 0;
+    for (const ch of line) {
+        if (ch === '{')
+            delta += 1;
+        else if (ch === '}')
+            delta -= 1;
+    }
+    return delta;
+}
 function splitWords(value) {
     return value.split(/\s+/).map(part => part.trim()).filter(Boolean);
 }

package/package.json

@@ -1,24 +1,24 @@
-{
-  "name": "cwtools-shared",
-  "version": "0.2.1",
-  "description": "Shared protocol and tool contracts for the CWTools MCP server",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Aa728848/cwtools-mcp.git"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "package.json"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build",
-    "test:contracts": "ts-mocha -p tsconfig.test.json \"src/test/**/*.test.ts\""
-  }
-}
+{
+  "name": "cwtools-shared",
+  "version": "0.2.3",
+  "description": "Shared protocol and tool contracts for the CWTools MCP server",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aa728848/cwtools-mcp.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test:contracts": "ts-mocha -p tsconfig.test.json \"src/test/**/*.test.ts\""
+  }
+}