@lousy-agents/lint 5.11.4 → 5.12.0

package/dist/index.js

@@ -895,7 +895,8 @@ __webpack_require__.d(classic_schemas_namespaceObject, {
         "instruction/parse-error": "warn",
         "instruction/command-not-in-code-block": "warn",
         "instruction/command-outside-section": "warn",
-        "instruction/missing-error-handling": "warn"
+        "instruction/missing-error-handling": "warn",
+        "instruction/missing-structural-heading": "warn"
     },
     skills: {
         "skill/invalid-frontmatter": "error",
@@ -37011,6 +37012,24 @@ core_config(en());
     "Validation Suite",
     "Commands"
 ];
+/**
+ * Descriptions for each default structural heading pattern explaining why it is recommended.
+ * Keyed by Record<StructuralHeadingPattern, string> to ensure compile-time coverage — every
+ * entry in DEFAULT_STRUCTURAL_HEADING_PATTERNS must have a description here.
+ */ const HEADING_PATTERN_DESCRIPTION_RECORD = {
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Validation: "Agents need this section to understand how to validate that their changes meet quality standards.",
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Verification: "Agents need this section to understand how to verify their implementation is correct.",
+    "Feedback Loop": "Agents need this section to understand the iterative improvement process to follow.",
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Mandatory: "Agents need this section to understand which steps are required and cannot be skipped.",
+    "Before Commit": "Agents need this section to know what checks to run before committing changes.",
+    "Validation Suite": "Agents need this section to know which validation commands to run against the codebase.",
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Commands: "Agents need this section to know which commands and tools are available in the project."
+};
+const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESCRIPTION_RECORD));
 /** Conditional keywords indicating error handling near code blocks */ const CONDITIONAL_KEYWORDS = [
     "if",
     "fail",
@@ -37030,6 +37049,24 @@ core_config(en());
  * Use case for analyzing instruction quality across a repository.
  * Orchestrates discovery, AST parsing, and scoring of feedback loop documentation.
  */ 
+
+/** Maximum number of raw heading pattern entries accepted before deduplication. */ const MAX_RAW_HEADING_PATTERNS = 1000;
+/** Maximum number of heading patterns accepted in a single execute() call. */ const MAX_HEADING_PATTERNS = 50;
+/** Maximum character length for a single heading pattern. */ const MAX_PATTERN_LENGTH = 200;
+/**
+ * Lowercase-keyed lookup built once from HEADING_PATTERN_DESCRIPTIONS.
+ * Enables description lookup regardless of the casing callers supply for patterns.
+ */ const HEADING_DESCRIPTIONS_BY_LOWER = new Map(Array.from(HEADING_PATTERN_DESCRIPTIONS, ([k, v])=>[
+        k.toLowerCase(),
+        v
+    ]));
+/**
+ * Input for the analyze instruction quality use case.
+ */ const AnalyzeInstructionQualityInputSchema = schemas_object({
+    targetDir: schemas_string().min(1, "Target directory is required"),
+    headingPatterns: schemas_array(schemas_string().max(MAX_PATTERN_LENGTH * 2)).max(MAX_RAW_HEADING_PATTERNS).optional(),
+    proximityWindow: schemas_number().int().positive().optional()
+});
 /**
  * Use case for analyzing instruction quality.
  */ class AnalyzeInstructionQualityUseCase {
@@ -37041,16 +37078,107 @@ core_config(en());
         this.astGateway = astGateway;
         this.commandsGateway = commandsGateway;
     }
+    /**
+     * Returns true if the given heading-pattern string contains any characters
+     * that could cause terminal injection or garbled output when the pattern
+     * is embedded in a diagnostic message.
+     *
+     * Rejects: ASCII C0 (0x00–0x1F), DEL (0x7F), C1 (0x80–0x9F), **lone**
+     * Unicode surrogates (U+D800–U+DFFF — but valid surrogate pairs like emoji
+     * are accepted), line/paragraph separators (U+2028–U+2029), and bidi
+     * override characters (U+202A–U+202E, U+2066–U+2069).
+     */ static patternHasControlCharacters(value) {
+        for(let i = 0; i < value.length; i++){
+            const code = value.charCodeAt(i);
+            if (code <= 0x1f) return true;
+            if (code === 0x7f) return true;
+            if (code >= 0x80 && code <= 0x9f) return true;
+            // Detect lone surrogates only; valid surrogate pairs (e.g., emoji)
+            // should be accepted. A high surrogate (0xD800–0xDBFF) is lone if
+            // it is not immediately followed by a low surrogate (0xDC00–0xDFFF).
+            if (code >= 0xd800 && code <= 0xdbff) {
+                const next = value.charCodeAt(i + 1);
+                if (next >= 0xdc00 && next <= 0xdfff) {
+                    i++; // valid pair — skip the low surrogate
+                } else {
+                    return true; // lone high surrogate
+                }
+            } else if (code >= 0xdc00 && code <= 0xdfff) {
+                return true; // lone low surrogate
+            }
+            if (code === 0x2028 || code === 0x2029) return true;
+            if (code >= 0x202a && code <= 0x202e) return true;
+            if (code >= 0x2066 && code <= 0x2069) return true;
+        }
+        return false;
+    }
+    /**
+     * Serializes a heading pattern for safe inclusion in error messages.
+     * Produces a quoted, unambiguous representation by:
+     *   - Escaping `"` as `\"` and `\` as `\\` within printable ASCII (0x20–0x7E)
+     *   - Escaping every code unit outside that range to `\uXXXX`
+     *
+     * The \uXXXX escaping prevents terminal injection via bidi override
+     * characters and other non-printable code points that JSON.stringify does
+     * not escape.
+     */ static serializePatternForError(value) {
+        let result = '"';
+        for(let i = 0; i < value.length; i++){
+            const code = value.charCodeAt(i);
+            if (code >= 0x20 && code <= 0x7e) {
+                if (code === 0x22) {
+                    result += '\\"';
+                } else if (code === 0x5c) {
+                    result += "\\\\";
+                } else {
+                    result += value[i];
+                }
+            } else {
+                result += `\\u${code.toString(16).padStart(4, "0")}`;
+            }
+        }
+        return `${result}"`;
+    }
     async execute(input) {
-        if (!input.targetDir) {
-            throw new Error("Target directory is required");
+        let parsed;
+        try {
+            parsed = AnalyzeInstructionQualityInputSchema.parse(input);
+        } catch (error) {
+            if (error instanceof ZodError) {
+                throw new Error(error.issues[0]?.message ?? "Validation failed: unable to parse error details");
+            }
+            throw error;
         }
-        const headingPatterns = input.headingPatterns ?? [
+        const seenLower = new Set();
+        const headingPatterns = [];
+        for (const raw of parsed.headingPatterns ?? [
             ...DEFAULT_STRUCTURAL_HEADING_PATTERNS
-        ];
-        const proximityWindow = input.proximityWindow ?? 3;
-        const discoveredFiles = await this.discoveryGateway.discoverInstructionFiles(input.targetDir);
-        const mandatoryCommands = await this.commandsGateway.getMandatoryCommands(input.targetDir);
+        ]){
+            // Validate BEFORE trim() — U+2028/U+2029 are JavaScript whitespace
+            // and would be silently stripped by trim(), bypassing the check.
+            // Filter before transform.
+            if (AnalyzeInstructionQualityUseCase.patternHasControlCharacters(raw)) {
+                throw new Error(`headingPatterns must not contain control characters, bidi override characters, or lone surrogate code points: ${AnalyzeInstructionQualityUseCase.serializePatternForError(raw)}`);
+            }
+            const trimmed = raw.trim();
+            if (trimmed.length === 0) {
+                throw new Error("headingPatterns must not contain empty or whitespace-only entries");
+            }
+            if (trimmed.length > MAX_PATTERN_LENGTH) {
+                throw new Error(`headingPatterns entries must not exceed ${MAX_PATTERN_LENGTH} characters`);
+            }
+            const lower = trimmed.toLowerCase();
+            if (!seenLower.has(lower)) {
+                seenLower.add(lower);
+                if (seenLower.size > MAX_HEADING_PATTERNS) {
+                    throw new Error(`headingPatterns must contain at most ${MAX_HEADING_PATTERNS} unique entries (case-insensitive)`);
+                }
+                headingPatterns.push(trimmed);
+            }
+        }
+        const proximityWindow = parsed.proximityWindow ?? 3;
+        const discoveredFiles = await this.discoveryGateway.discoverInstructionFiles(parsed.targetDir);
+        const mandatoryCommands = await this.commandsGateway.getMandatoryCommands(parsed.targetDir);
         if (discoveredFiles.length === 0) {
             return {
                 result: {
@@ -37083,7 +37211,7 @@ core_config(en());
             }
         }
         // Sort parsing errors for deterministic output
-        parsingErrors.sort((a, b)=>a.filePath.localeCompare(b.filePath));
+        parsingErrors.sort((a, b)=>a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0);
         // Score each mandatory command across all files
         const commandScores = [];
         const diagnostics = [];
@@ -37098,6 +37226,16 @@ core_config(en());
                 target: "instruction"
             });
         }
+        // Check each successfully parsed file for missing structural headings
+        const sortedFilePaths = Array.from(fileStructures.keys()).sort((a, b)=>a < b ? -1 : a > b ? 1 : 0);
+        for (const filePath of sortedFilePaths){
+            const structure = fileStructures.get(filePath);
+            if (!structure) {
+                continue;
+            }
+            const missingDiagnostics = this.checkMissingHeadings(filePath, structure, headingPatterns);
+            diagnostics.push(...missingDiagnostics);
+        }
         for (const command of mandatoryCommands){
             const bestAnalysis = this.findBestScore(command, discoveredFiles, fileStructures, headingPatterns, proximityWindow, diagnostics);
             if (bestAnalysis) {
@@ -37339,6 +37477,43 @@ core_config(en());
         }
         return false;
     }
+    /**
+     * Emits a warning diagnostic for each heading pattern that is absent from the file.
+     * Headings are matched case-insensitively using substring inclusion, matching the
+     * same logic used elsewhere in the use case.
+     */ checkMissingHeadings(filePath, structure, headingPatterns) {
+        // Precondition: `headingPatterns` must already be deduplicated
+        // (case-insensitively) and validated. This invariant is enforced by
+        // `execute()` before calling this method.
+        const diagnostics = [];
+        const fileHeadingTexts = structure.headings.map((h)=>h.text.toLowerCase());
+        for (const pattern of headingPatterns){
+            const patternLower = pattern.toLowerCase();
+            const hasHeading = fileHeadingTexts.some((text)=>{
+                if (!text.includes(patternLower)) {
+                    return false;
+                }
+                // Don't let a heading satisfy a shorter pattern when it also satisfies
+                // a longer, more-specific pattern that starts with the shorter one.
+                // E.g., a "Validation Suite" heading satisfies "Validation Suite" but
+                // should NOT also satisfy "Validation".
+                const supersededByMoreSpecific = headingPatterns.some((other)=>other !== pattern && other.toLowerCase().startsWith(patternLower) && text.includes(other.toLowerCase()));
+                return !supersededByMoreSpecific;
+            });
+            if (!hasHeading) {
+                const description = HEADING_DESCRIPTIONS_BY_LOWER.get(patternLower) ?? "This heading helps guide coding agents through structured workflows.";
+                diagnostics.push({
+                    filePath,
+                    line: 1,
+                    severity: "warning",
+                    message: `Missing '${pattern}' heading section. ${description}`,
+                    ruleId: "instruction/missing-structural-heading",
+                    target: "instruction"
+                });
+            }
+        }
+        return diagnostics;
+    }
     generateSuggestions(commandScores) {
         const suggestions = [];
         const lowStructural = commandScores.filter((s)=>s.structuralContext === 0 && s.bestSourceFile !== "");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lousy-agents/lint",
-    "version": "5.11.4",
+    "version": "5.12.0",
     "description": "Programmatic lint API for validating AI coding assistant configurations — skills, agents, hooks, and instructions",
     "type": "module",
     "repository": {