@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/lint/reporters.js

@@ -31,14 +31,33 @@ function formatDiagnostic(d) {
 /**
  * Format lint results in full detail
  */
+function formatBudget(result) {
+    const report = result.inlineBudget;
+    if (!report)
+        return [];
+    return [
+        `Startup budget (${report.provider}): limit ${report.limit} tokens${report.disabled ? ' (guard disabled)' : ''}; selected ${report.selected_tokens} estimated tokens (${report.selected_bytes} bytes; ${report.estimate})`,
+        ...report.contributors.map(file => `  ${file.path}: ${file.bytes} bytes (${file.estimated_tokens} estimated tokens)`),
+    ];
+}
 function formatFull(result) {
     const lines = [];
     lines.push(`${BOLD}AIWG Lint${RESET}`);
     lines.push(`Target: ${result.target}`);
     lines.push(`Rulesets: ${result.rulesets.join(', ')}`);
     lines.push(`Files checked: ${result.summary.filesChecked}`);
+    lines.push(...formatBudget(result));
     lines.push(`Rules applied: ${result.summary.rulesApplied} of ${result.summary.rulesSelected}`);
     lines.push('');
+    if (result.summary.coverageMessage)
+        lines.push(`! ${result.summary.coverageMessage}`);
+    if (result.ruleCoverage) {
+        lines.push('Rule coverage (files by rule):');
+        for (const [ruleId, files] of Object.entries(result.ruleCoverage)) {
+            lines.push(`  ${ruleId}: ${files.length ? files.join(', ') : '(no files)'}`);
+        }
+        lines.push('');
+    }
     // A target that excludes every rule produces the same clean output as a
     // target that passes them, which is how 34 findings stayed invisible across a
     // long session (#2555). Say so before the verdict.
@@ -92,9 +111,14 @@ function formatFull(result) {
  * Format lint results as a summary (counts only)
  */
 function formatSummary(result) {
-    const lines = [];
+    const lines = [...formatBudget(result)];
     lines.push(`Lint: ${result.summary.filesChecked} files, ${result.summary.errors} errors, ${result.summary.warnings} warnings, ${result.summary.infos} info`);
     lines.push(`Rules applied: ${result.summary.rulesApplied} of ${result.summary.rulesSelected}`);
+    if (result.summary.coverageMessage)
+        lines.push(`! ${result.summary.coverageMessage}`);
+    if (result.summary.inapplicableRules.length > 0) {
+        lines.push(`Inapplicable rules: ${result.summary.inapplicableRules.join(', ')}`);
+    }
     if (result.summary.rulesSelected > 0 && result.summary.rulesApplied === 0) {
         lines.push(`! No rule applies to this target — this is not a clean result (#2555).`);
     }

package/dist/src/lint/rule-activation.js

@@ -0,0 +1,43 @@
+import { loadLocalCapabilityEntries, resolveRuleBindingTarget } from '../artifacts/query-engine.js';
+import { parseRuleFrontmatter, RULE_BINDING_TYPES } from '../rules/activation.mjs';
+export const ruleActivationRuleset = {
+    id: 'rule-activation', name: 'Rule activation', framework: 'core', version: '1.0.0',
+    description: 'Validate rule and behavior activation contracts and exact indexed bindings',
+    rules: [{
+            id: 'rules/activation', name: 'Rule activation contract', severity: 'error',
+            description: 'Validate activation, summaries, paths, bindings, and migration fallback',
+            appliesTo: { glob: '**/{rules/**/*.md,behaviors/**/BEHAVIOR.md}' },
+            checks: [{ type: 'rule-activation' }],
+        }],
+};
+export function lintRuleActivation(content, file, projectRoot, entries) {
+    // Generated structural indexes are not authored rules.
+    if (/^(?:RULES-INDEX|RULES-ONDEMAND)\.md$/.test(file.split('/').pop()))
+        return [];
+    const result = parseRuleFrontmatter(content);
+    const diagnostics = result.diagnostics.map(item => ({
+        ruleId: 'rules/activation', ruleName: 'Rule activation contract',
+        file, severity: item.severity, message: item.message,
+    }));
+    if (!result.rule)
+        return diagnostics;
+    const bindings = result.rule.bound_to;
+    if (!Object.values(bindings).some(list => list.length > 0))
+        return diagnostics;
+    // Reuse existing artifact index ownership and show precedence. No title guessing,
+    // corpus directory resolver, or extra binding registry.
+    const indexed = entries ?? loadLocalCapabilityEntries(projectRoot);
+    for (const key of Object.keys(RULE_BINDING_TYPES)) {
+        for (const id of bindings[key]) {
+            try {
+                resolveRuleBindingTarget(indexed, RULE_BINDING_TYPES[key], id);
+            }
+            catch (error) {
+                diagnostics.push({ ruleId: 'rules/activation', ruleName: 'Rule activation contract',
+                    file, severity: 'error', message: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=rule-activation.js.map

package/dist/src/lint/runner.js

@@ -7,27 +7,54 @@
  * @issue #810
  */
 import fs from 'fs';
-import { spawnSync } from 'child_process';
+import { lintRuleActivation } from './rule-activation.js';
+import { guardRulesInlineBudget } from '../rules/inline-budget.mjs';
+import { dropGitignored } from '../config/gitignore.js';
 import fsp from 'fs/promises';
 import path from 'path';
 import { glob } from 'glob';
 import { minimatch } from 'minimatch';
+import { parse } from 'yaml';
 /**
  * Parse YAML-style frontmatter from a markdown file
  * Returns key-value pairs from the --- delimited block
  */
 function parseFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
     if (!match)
         return {};
-    const result = {};
-    for (const line of match[1].split('\n')) {
-        const kv = line.match(/^(\w[\w-]*)\s*:\s*(.+)$/);
-        if (kv) {
-            result[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+    try {
+        const parsed = parse(match[1]);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        // Invalid YAML cannot supply required metadata.
+        return {};
+    }
+}
+function isPresent(value) {
+    if (value == null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+/** Resolve project-relative metadata from the nearest repository/workspace marker. */
+function findProjectRoot(targetDir) {
+    let dir = path.resolve(targetDir);
+    while (true) {
+        if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.aiwg'))) {
+            return dir;
         }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return path.resolve(targetDir);
+        dir = parent;
     }
-    return result;
 }
 const DEFAULT_REFERENCE_PATTERN = '\\bREF-\\d{3,}\\b';
 /**
@@ -215,8 +242,9 @@ function buildReferenceIndex(allFiles) {
  * Preserve support for references stored outside the lint target when a rule
  * explicitly supplies basePath. Accept both exact and slugged filenames.
  */
-function resolvesFromBasePath(refId, targetDir, basePath) {
+function resolvesFromBasePath(refId, targetDir, basePath, projectRoot) {
     const candidateDirs = new Set([
+        path.resolve(projectRoot, basePath),
         path.resolve(targetDir, basePath),
         path.resolve(process.cwd(), basePath),
     ]);
@@ -237,14 +265,14 @@ function resolvesFromBasePath(refId, targetDir, basePath) {
 /**
  * Run a single check against a file's content and frontmatter
  */
-function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, referenceIndex) {
+function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, referenceIndex, projectRoot) {
     const diagnostics = [];
     switch (check.type) {
         case 'frontmatter-required': {
             if (!check.fields)
                 break;
             for (const field of check.fields) {
-                if (!frontmatter[field] || frontmatter[field].trim() === '') {
+                if (!isPresent(frontmatter[field])) {
                     diagnostics.push({
                         ruleId: '',
                         ruleName: '',
@@ -261,7 +289,7 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
             if (!check.field || !check.pattern)
                 break;
             const value = frontmatter[check.field];
-            if (value && !new RegExp(check.pattern).test(value)) {
+            if (isPresent(value) && typeof value !== 'object' && !new RegExp(check.pattern).test(String(value))) {
                 diagnostics.push({
                     ruleId: '',
                     ruleName: '',
@@ -282,7 +310,9 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
                 let match;
                 while ((match = regex.exec(lines[i])) !== null) {
                     const refId = match[0];
-                    const basePath = check.basePath || '.aiwg/research/findings';
+                    const basePaths = check.basePath
+                        ? [check.basePath]
+                        : ['.aiwg/research/findings', 'findings', 'documentation/references', '.'];
                     // A corpus documents its deliberate gaps ("REF-2464 remains
                     // unallocated after deduplication"). Reading that sentence as a
                     // dangling reference left only two ways to silence an error: delete
@@ -290,7 +320,7 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
                     // absent (#2555).
                     if (absence.some((re) => re.test(lines[i])))
                         continue;
-                    if (!referenceIndex.has(refId) && !resolvesFromBasePath(refId, targetDir, basePath)) {
+                    if (!referenceIndex.has(refId) && !basePaths.some(basePath => resolvesFromBasePath(refId, targetDir, basePath, projectRoot))) {
                         diagnostics.push({
                             ruleId: '',
                             ruleName: '',
@@ -376,9 +406,12 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
             if (!check.field)
                 break;
             const refPath = frontmatter[check.field];
-            if (refPath) {
-                const resolved = path.resolve(targetDir, refPath);
-                if (!fs.existsSync(resolved)) {
+            if (isPresent(refPath)) {
+                // Project-root-relative is canonical (#3145); target-relative paths
+                // written for the legacy layout keep resolving.
+                const found = typeof refPath === 'string' &&
+                    [projectRoot, targetDir].some(base => fs.existsSync(path.resolve(base, refPath)));
+                if (!found) {
                     diagnostics.push({
                         ruleId: '',
                         ruleName: '',
@@ -398,7 +431,8 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
             if (!check.pattern)
                 break;
             const basename = path.basename(filePath, '.md');
-            if (!new RegExp(check.pattern).test(basename)) {
+            const match = basename.match(new RegExp(check.pattern));
+            if (!match) {
                 diagnostics.push({
                     ruleId: '',
                     ruleName: '',
@@ -408,6 +442,20 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
                     fix: `Rename to match the pattern ${check.pattern}`,
                 });
             }
+            else if (check.field && isPresent(frontmatter[check.field])) {
+                const identifier = match[1] ?? match[0];
+                const value = frontmatter[check.field];
+                if (value !== identifier) {
+                    diagnostics.push({
+                        ruleId: '',
+                        ruleName: '',
+                        severity: 'warn',
+                        file: filePath,
+                        message: `File identifier '${identifier}' does not match frontmatter field '${check.field}': ${String(value)}`,
+                        fix: `Make the filename identifier and '${check.field}' field agree`,
+                    });
+                }
+            }
             break;
         }
         case 'cross-ref-bidirectional': {
@@ -473,15 +521,13 @@ export function ruleAppliesToFile(ruleGlob, file, targetDir) {
 /**
  * Run a single rule against all matching files in the target
  */
-async function runRule(rule, targetDir, allFiles, referenceIndex) {
+async function runRule(rule, targetDir, allFiles, referenceIndex, projectRoot, artifactEntries) {
     const diagnostics = [];
-    RULE_APPLIED.delete(rule.id);
     // Filter files matching the rule's glob
     const ruleGlob = rule.appliesTo.glob;
     const matchingFiles = allFiles.filter(f => ruleAppliesToFile(ruleGlob, f, targetDir));
     if (matchingFiles.length === 0)
-        return diagnostics;
-    RULE_APPLIED.add(rule.id);
+        return { diagnostics, files: matchingFiles };
     // Handle id-unique check at the ruleset level
     const uniqueCheck = rule.checks.find(c => c.type === 'id-unique');
     if (uniqueCheck) {
@@ -516,7 +562,11 @@ async function runRule(rule, targetDir, allFiles, referenceIndex) {
         for (const check of rule.checks) {
             if (check.type === 'id-unique')
                 continue; // Already handled
-            const checkDiagnostics = runCheck(check, content, frontmatter, file, targetDir, allFiles, referenceIndex);
+            if (check.type === 'rule-activation') {
+                diagnostics.push(...lintRuleActivation(content, file, projectRoot, artifactEntries));
+                continue;
+            }
+            const checkDiagnostics = runCheck(check, content, frontmatter, file, targetDir, allFiles, referenceIndex, projectRoot);
             for (const d of checkDiagnostics) {
                 d.ruleId = rule.id;
                 d.ruleName = rule.name;
@@ -525,10 +575,8 @@ async function runRule(rule, targetDir, allFiles, referenceIndex) {
             }
         }
     }
-    return diagnostics;
+    return { diagnostics, files: matchingFiles };
 }
-/** Rule ids that selected at least one file in the current run (#2555). */
-const RULE_APPLIED = new Set();
 /**
  * Collect all files under a target directory
  */
@@ -547,37 +595,6 @@ async function collectFiles(targetDir, recursive, respectGitignore = true) {
         return [];
     }
 }
-/**
- * Drop files git ignores (#2555).
- *
- * Generated trees are regenerated, not authored: linting `indices/` reported an
- * error in text that documents a deliberate gap. `git check-ignore` is asked
- * once for the whole set so the semantics are git's own (negations, nested
- * `.gitignore`, `core.excludesFile`) rather than a re-implementation. Outside a
- * repository, or without git, every file is kept.
- */
-function dropGitignored(targetDir, files) {
-    if (files.length === 0)
-        return files;
-    try {
-        const result = spawnSync('git', ['check-ignore', '--stdin'], {
-            cwd: targetDir,
-            input: `${files.join('\n')}\n`,
-            encoding: 'utf8',
-        });
-        // 0 = some paths ignored, 1 = none ignored, anything else = not a repo or
-        // git unavailable, in which case nothing is filtered.
-        if (result.error || (result.status !== 0 && result.status !== 1))
-            return files;
-        const ignored = new Set((result.stdout ?? '').split('\n').map((line) => line.trim()).filter(Boolean));
-        if (ignored.size === 0)
-            return files;
-        return files.filter((file) => !ignored.has(file));
-    }
-    catch {
-        return files;
-    }
-}
 /**
  * Auto-detect which rulesets apply to a target path
  *
@@ -602,27 +619,74 @@ function autoDetectRulesets(target, available) {
         }
     }
     // If no auto-detection, return all available
-    return matches.length > 0 ? matches : available;
+    return matches.length > 0
+        ? available.filter(ruleset => ruleset.id === 'rule-activation' || matches.includes(ruleset))
+        : available;
 }
 /**
  * Run lint on a target path with specified or auto-detected rulesets
  */
 export async function runLint(targetDir, rulesets, options = {}) {
     const recursive = options.recursive ?? true;
-    const allFiles = await collectFiles(targetDir, recursive, options.respectGitignore ?? true);
+    const targetStat = await fsp.stat(targetDir).catch(() => null);
+    const scanDir = targetStat?.isFile() ? path.dirname(targetDir) : targetDir;
+    const projectRoot = findProjectRoot(scanDir);
+    const respectGitignore = options.respectGitignore ?? true;
+    let allFiles;
+    let targetMessage = '';
+    if (!targetStat) {
+        allFiles = [];
+        targetMessage = `Target does not exist or is inaccessible: ${targetDir}.`;
+    }
+    else if (targetStat.isFile()) {
+        const file = path.basename(targetDir);
+        if (!/\.(md|yaml|yml|json)$/.test(file)) {
+            allFiles = [];
+            targetMessage = `Unsupported file type: ${file}. Expected .md, .yaml, .yml or .json.`;
+        }
+        else {
+            allFiles = respectGitignore ? dropGitignored(scanDir, [file]) : [file];
+        }
+    }
+    else {
+        allFiles = await collectFiles(scanDir, recursive, respectGitignore);
+    }
     const referenceIndex = buildReferenceIndex(allFiles);
     const allDiagnostics = [];
     const inapplicableRules = [];
+    const ruleCoverage = {};
     let rulesSelected = 0;
     for (const ruleset of rulesets) {
         for (const rule of ruleset.rules) {
             rulesSelected += 1;
-            const diagnostics = await runRule(rule, targetDir, allFiles, referenceIndex);
-            if (!RULE_APPLIED.has(rule.id))
+            const { diagnostics, files } = await runRule(rule, scanDir, allFiles, referenceIndex, projectRoot, options.artifactEntries);
+            ruleCoverage[rule.id] = files;
+            if (files.length === 0)
                 inapplicableRules.push(rule.id);
             allDiagnostics.push(...diagnostics);
         }
     }
+    let budget;
+    if (options.startupBudget) {
+        try {
+            budget = guardRulesInlineBudget({
+                ...options.startupBudget, reportOnly: options.ci ? false : (options.startupBudget.reportOnly ?? true),
+            });
+        }
+        catch (error) {
+            allDiagnostics.push({
+                ruleId: 'rules/inline-budget', ruleName: 'Rules inline budget', file: '(assembled startup)',
+                severity: 'error', message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (budget) {
+        for (const item of budget.diagnostics)
+            allDiagnostics.push({
+                ruleId: 'rules/inline-budget', ruleName: 'Rules inline budget', file: '(assembled startup)',
+                severity: item.severity, message: item.message,
+            });
+    }
     const errors = allDiagnostics.filter(d => d.severity === 'error').length;
     const warnings = allDiagnostics.filter(d => d.severity === 'warn').length;
     const infos = allDiagnostics.filter(d => d.severity === 'info').length;
@@ -634,10 +698,20 @@ export async function runLint(targetDir, rulesets, options = {}) {
         passed = false;
     if (failOn === 'info' && allDiagnostics.length > 0)
         passed = false;
+    const rulesApplied = rulesSelected - inapplicableRules.length;
+    const coverageMessage = allFiles.length === 0
+        ? `No files checked. ${targetMessage || 'The target is empty, contains no supported files, or all files are ignored.'}`
+        : rulesApplied === 0
+            ? 'No rules applied. Check the target path and selected ruleset globs.'
+            : undefined;
+    if (options.ci && !options.allowEmpty && coverageMessage)
+        passed = false;
     return {
         target: targetDir,
         rulesets: rulesets.map(r => r.id),
         diagnostics: allDiagnostics,
+        ...(budget ? { inlineBudget: budget.report } : {}),
+        ruleCoverage,
         summary: {
             filesChecked: allFiles.length,
             errors,
@@ -647,8 +721,9 @@ export async function runLint(targetDir, rulesets, options = {}) {
             // A run where no rule selected a file must never read the same as a clean
             // run (#2555). Reporters surface this; callers can gate on it.
             rulesSelected,
-            rulesApplied: rulesSelected - inapplicableRules.length,
+            rulesApplied,
             inapplicableRules,
+            coverageMessage,
         },
         timestamp: new Date().toISOString(),
     };