@promptci/core 0.0.1

package/dist/stale-instructions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stale-instruction detector for PromptCI.
+ *
+ * Flags sections that likely reference outdated content:
+ *   - Years 2019–2023 that appear outside code blocks
+ *   - Cleanup keywords: "TODO remove", "remove later", "temporary fix", "workaround"
+ *   - "deprecated" near a version number or tool name
+ *   - Known old framework versions (React 16, Next.js 9, Unity 2019, etc.)
+ *
+ * Findings are heuristic — wording is intentionally cautious.
+ */
+import type { InstructionFile, PromptCiIssue } from './types.js';
+/**
+ * Detect sections that may contain stale or outdated instructions.
+ *
+ * Returns one issue per offending section (multiple patterns in the same
+ * section are merged into a single issue).
+ */
+export declare function detectStaleInstructions(files: InstructionFile[]): PromptCiIssue[];
+//# sourceMappingURL=stale-instructions.d.ts.map

package/dist/stale-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-instructions.d.ts","sourceRoot":"","sources":["../src/stale-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAsB,aAAa,EAAE,MAAM,YAAY,CAAC;AAqMrF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAwFjF"}

package/dist/stale-instructions.js

@@ -0,0 +1,269 @@
+/**
+ * Stale-instruction detector for PromptCI.
+ *
+ * Flags sections that likely reference outdated content:
+ *   - Years 2019–2023 that appear outside code blocks
+ *   - Cleanup keywords: "TODO remove", "remove later", "temporary fix", "workaround"
+ *   - "deprecated" near a version number or tool name
+ *   - Known old framework versions (React 16, Next.js 9, Unity 2019, etc.)
+ *
+ * Findings are heuristic — wording is intentionally cautious.
+ */
+import * as crypto from 'node:crypto';
+// ─── Pattern definitions ──────────────────────────────────────────────────────
+/**
+ * Years likely stale in an AI instruction context.
+ * 2023 is now included since the current year is 2026.
+ * Must not be immediately preceded by "/" or "-" (avoids ISO dates like 2022-01-01
+ * or paths like /2022/report) — those are not year references.
+ */
+const STALE_YEAR_RE = /(?<![/-])\b(2019|2020|2021|2022|2023|2024|2025)\b(?![/-])/g;
+/**
+ * BUG-A1: Section headings that indicate historical records rather than active
+ * instructions. Old year references in changelogs and release notes are expected
+ * and must not be flagged as stale instructions.
+ */
+const HISTORY_SECTION_RE = /\b(?:history|changelog|change\s*log|release\s+notes?|releases?|versions?|what.?s\s+new|for\s+reference)\b/i;
+/** Explicit cleanup markers. */
+const CLEANUP_KEYWORD_RE = /\b(TODO\s*:?\s*remove|remove\s+later|temporary\s+fix|workaround)\b/gi;
+/**
+ * BUG-004: Dated TODO/FIXME/WORKAROUND markers inside HTML comments.
+ * The main STALE_YEAR_RE intentionally excludes ISO-formatted dates like 2022-03-10
+ * (using a negative lookahead on "/"). This separate pattern catches years that appear
+ * inside parenthesised dates in HTML comments, e.g.:
+ *   <!-- TODO (2022-03-10): migrate NextAuth v3 callbacks -->
+ *   <!-- WORKAROUND (2021-08-14): ... -->
+ * Groups: [1]=keyword, [2]=year
+ *
+ * ST1: Both `(?:(?!-->)[\s\S])*?` spans use a "tempered dot" — match anything
+ * (including newlines) as long as it's not the start of the comment's closing
+ * `-->`. This allows the keyword and its date to be split across lines
+ * (`<!-- TODO\n(2022-03-10): ... -->`) and allows ordinary `>` characters
+ * before the keyword (`<!-- if retries > 3 TODO (2022-01-01): remove -->`),
+ * neither of which the old `[^>]*?` / `[^(>\n]*` classes permitted, while
+ * still stopping at the actual end of the same comment.
+ */
+const HTML_COMMENT_DATED_TODO_RE = /<!--(?:(?!-->)[\s\S])*?\b(TODO|FIXME|WORKAROUND|HACK|NOTE)\b(?:(?!-->)[\s\S])*?\(\s*(\d{4})[-–\d]/gi;
+/**
+ * "deprecated" within ~10 words of a version number or recognisable tool name.
+ */
+const DEPRECATED_NEAR_VERSION_RE = /deprecated[\w\s,.()\\\-:`]{0,60}(v?\d+[\w.]+|react|next\.?js|angular|vue|webpack|babel|unity|jest|mocha)/gi;
+/**
+ * Known old framework/library versions that signal stale instructions.
+ *
+ * ST2: Every numeric version is prefixed with an optional `v?` so aliases
+ * like "React v16", "Node v12", "Angular v8" are caught too — the old
+ * patterns only matched the bare-number form, which was inconsistent with
+ * manifest-consistency.ts's checkNodeVersionMismatch (which already accepts
+ * `v?`).
+ */
+const OLD_VERSION_PATTERNS = [
+    { re: /\breact\s+v?1[0-6]\b/gi, label: 'React 16 or earlier' },
+    { re: /\bnext\.?js\s+v?[1-9]\b/gi, label: 'Next.js 9 or earlier' },
+    { re: /\bunity\s+v?201[0-9]\b/gi, label: 'Unity 2019 or earlier' },
+    { re: /\bangular\s+v?[1-9]\b/gi, label: 'Angular 9 or earlier' },
+    { re: /\bvue\s+v?[12]\b/gi, label: 'Vue 2 or earlier' },
+    { re: /\bwebpack\s+v?[1-3]\b/gi, label: 'Webpack 3 or earlier' },
+    { re: /\bbabel\s+v?[1-6]\b/gi, label: 'Babel 6 or earlier' },
+    // BUG-005: Fixed — original pattern required "node.js" (with .js); bare "Node 12" was missed.
+    //          Extended range to 16 since Node 14 & 16 are also EOL.
+    { re: /\bnode(?:\.js?)?\s+v?(1[0-6]|[1-9])\b/gi, label: 'Node.js 16 or earlier' },
+    { re: /\btypescript\s+v?[1-3]\b/gi, label: 'TypeScript 3 or earlier' },
+    // BUG-005: Added Go — Go 1.17 and earlier pre-date generics (1.18) and are commonly stale.
+    { re: /\bgo\s+v?1\.(1[0-7]|[0-9])\b/gi, label: 'Go 1.17 or earlier' },
+    // BUG-005: Added Python 2 — Python 2 reached EOL in 2020.
+    { re: /\bpython\s+v?2\./gi, label: 'Python 2' },
+    // BUG-G2: Python 3.9 and earlier are EOL (3.9 EOL Oct 2025, 3.8 Oct 2024, earlier all prior).
+    // Catches "Python 3.6", "Python 3.8", etc. without a 4-digit year.
+    { re: /\bpython\s+v?3\.[0-9]\b/gi, label: 'Python 3.9 or earlier' },
+    // BUG-005: Added .NET 5 and earlier (non-LTS / EOL versions).
+    { re: /\.NET\s+v?[1-5]\b/gi, label: '.NET 5 or earlier' },
+];
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function issueId(section, tag) {
+    const key = `${section.filePath}:${section.startLine}:${tag}`;
+    const hash = crypto.createHash('sha1').update(key).digest('hex').slice(0, 12);
+    return `stale-${hash}`;
+}
+function snippet(text, maxLen = 120) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    return clean.length <= maxLen ? clean : `${clean.slice(0, maxLen)}…`;
+}
+function collectMatches(text, re) {
+    const matches = [];
+    let m;
+    const cloned = new RegExp(re.source, re.flags);
+    while ((m = cloned.exec(text)) !== null) {
+        matches.push(m[0]);
+    }
+    return matches;
+}
+/**
+ * BUG-013: Returns {match, index} pairs so we can check whether each match
+ * occurs in a negation / avoidance context before flagging it as stale.
+ */
+function collectMatchesWithIndex(text, re) {
+    const results = [];
+    let m;
+    const cloned = new RegExp(re.source, re.flags);
+    while ((m = cloned.exec(text)) !== null) {
+        results.push({ match: m[0], index: m.index });
+    }
+    return results;
+}
+function collectOldHtmlTodoMatches(text) {
+    const matches = [];
+    let m;
+    const cloned = new RegExp(HTML_COMMENT_DATED_TODO_RE.source, HTML_COMMENT_DATED_TODO_RE.flags);
+    while ((m = cloned.exec(text)) !== null) {
+        const year = Number(m[2]);
+        if (year <= 2025) {
+            matches.push(m[0]);
+        }
+    }
+    return matches;
+}
+/**
+ * BUG-013: Detect whether an old-version reference is in a negation / avoidance
+ * context (e.g. "do not add Vue 2 compat", "avoid Vue 2", "dropped Vue 2 support").
+ *
+ * If so, the mention is a CURRENT rule ("don't use the old version") rather than
+ * a stale instruction, and should not be flagged.
+ *
+ * Looks at up to 80 chars before the match index for negation keywords.
+ *
+ * ST4: the trailing window only excludes sentence-ending punctuation
+ * (`.`/`!`/`?`), not newlines — a single hard-wrap ("Do not\nadd Vue 2...")
+ * no longer hides the negation keyword from the match. A BLANK line (a real
+ * paragraph break) still ends the window, via the `(?!\n[ \t]*\n)` tempered
+ * repetition, so negation from an unrelated earlier paragraph can't leak in.
+ */
+function isVersionInNegationContext(text, index) {
+    const preceding = text.slice(Math.max(0, index - 80), index).toLowerCase();
+    return /\b(?:do\s+not|don['']?t|avoid|never|no\s+longer|drop(?:ped|ping)?|remov(?:ed?|ing)|deprecat(?:ed?|ing)|stop(?:ped|ping)?\s+(?:using|support(?:ing)?))\b(?:(?!\n[ \t]*\n)[^.!?])*$/.test(preceding);
+}
+/**
+ * Strip fenced code blocks from text before scanning for stale years.
+ * Code blocks often contain version pins or changelog entries that are
+ * expected to reference specific years and should not trigger the detector.
+ *
+ * ST3: tracks fence character + length (matching scanner.ts's S1 fix and
+ * vague-guidance.ts's V4 fix) instead of a `` ```...``` `` regex, so ~~~
+ * fences are also stripped and an unclosed fence correctly swallows the
+ * remainder of the text (rather than leaving it unstripped, as
+ * `/```[\s\S]*?```/` did when no closing fence existed).
+ */
+function stripCodeBlocks(text, stripInlineCode = true) {
+    const lines = text.split('\n');
+    const kept = [];
+    let inBlock = false;
+    let fenceChar = null;
+    let fenceLen = 0;
+    for (const line of lines) {
+        if (!inBlock) {
+            const openMatch = /^ {0,3}([`~]{3,})/.exec(line);
+            if (openMatch) {
+                inBlock = true;
+                fenceChar = openMatch[1][0] ?? null;
+                fenceLen = openMatch[1].length;
+                continue;
+            }
+            kept.push(line);
+        }
+        else {
+            const closeMatch = /^ {0,3}([`~]{3,})\s*$/.exec(line);
+            if (closeMatch && closeMatch[1][0] === fenceChar && closeMatch[1].length >= fenceLen) {
+                inBlock = false;
+                fenceChar = null;
+                fenceLen = 0;
+            }
+            // else: still inside the fence — drop the line
+        }
+    }
+    const noFences = kept.join('\n');
+    return stripInlineCode ? noFences.replace(/`[^`\n]+`/g, '') : noFences;
+}
+// ─── Main detector ────────────────────────────────────────────────────────────
+/**
+ * Detect sections that may contain stale or outdated instructions.
+ *
+ * Returns one issue per offending section (multiple patterns in the same
+ * section are merged into a single issue).
+ */
+export function detectStaleInstructions(files) {
+    const issues = [];
+    const seen = new Set();
+    for (const file of files) {
+        for (const section of file.sections) {
+            // BUG-A1: Skip history/changelog/release-notes sections — old year references
+            // in these sections are historical records, not actionable instructions.
+            if (section.heading && HISTORY_SECTION_RE.test(section.heading))
+                continue;
+            const text = section.text;
+            const textNoCode = stripCodeBlocks(text);
+            const textNoFencedCode = stripCodeBlocks(text, false);
+            const evidence = [];
+            let confidence = 0;
+            const sectionKey = `${file.path}:${section.startLine}`;
+            // 1. Stale years — only in prose, not inside code blocks (confidence 0.6)
+            const yearMatches = collectMatches(textNoCode, STALE_YEAR_RE);
+            if (yearMatches.length > 0) {
+                evidence.push(`Year reference(s) that may be outdated: ${[...new Set(yearMatches)].join(', ')}`);
+                confidence = Math.max(confidence, 0.6);
+            }
+            // 2. Cleanup keywords (confidence 0.6)
+            const cleanupMatches = collectMatches(textNoFencedCode, CLEANUP_KEYWORD_RE);
+            if (cleanupMatches.length > 0) {
+                evidence.push(`Cleanup keyword(s): ${[...new Set(cleanupMatches.map((m) => m.trim()))].join(', ')}`);
+                confidence = Math.max(confidence, 0.6);
+            }
+            // 3. "deprecated" near version/tool (confidence 0.7)
+            const deprecatedMatches = collectMatches(textNoFencedCode, DEPRECATED_NEAR_VERSION_RE);
+            if (deprecatedMatches.length > 0) {
+                evidence.push(`"deprecated" near version/tool: ${snippet(deprecatedMatches[0] ?? '', 80)}`);
+                confidence = Math.max(confidence, 0.7);
+            }
+            // 4. Old framework versions (confidence 0.7)
+            // BUG-013: Skip matches that appear in a negation context
+            // ("do not add Vue 2 compat", "avoid Vue 2", etc.) — those are current rules,
+            // not stale instructions.
+            for (const { re, label } of OLD_VERSION_PATTERNS) {
+                const hits = collectMatchesWithIndex(textNoCode, re);
+                const relevantHits = hits.filter(({ index }) => !isVersionInNegationContext(textNoCode, index));
+                if (relevantHits.length > 0) {
+                    evidence.push(`Old version reference: ${label} ("${relevantHits[0].match}")`);
+                    confidence = Math.max(confidence, 0.7);
+                }
+            }
+            // 5. BUG-004: Dated TODO/FIXME/WORKAROUND in HTML comments.
+            // The main STALE_YEAR_RE skips ISO dates (2022-03-10) by design; this catches them
+            // specifically when they appear as a timestamp inside an HTML comment keyword.
+            const htmlTodoMatches = collectOldHtmlTodoMatches(textNoFencedCode);
+            if (htmlTodoMatches.length > 0) {
+                evidence.push(`Dated ${htmlTodoMatches[0].match(/TODO|FIXME|WORKAROUND|HACK|NOTE/i)?.[0] ?? 'TODO'} ` +
+                    `marker in HTML comment: ${snippet(htmlTodoMatches[0] ?? '', 80)}`);
+                confidence = Math.max(confidence, 0.65);
+            }
+            if (evidence.length === 0)
+                continue;
+            if (seen.has(sectionKey))
+                continue;
+            seen.add(sectionKey);
+            issues.push({
+                id: issueId(section, 'stale'),
+                severity: 'warning',
+                category: 'stale_instruction',
+                title: 'Instruction may reference outdated content',
+                summary: 'This instruction may reference outdated content. Review and update or remove it.',
+                filePaths: [file.path],
+                locations: [{ filePath: file.path, startLine: section.startLine, endLine: section.endLine }],
+                evidence: [`Section: "${snippet(text, 100)}"`, ...evidence],
+                recommendation: 'Review this section for accuracy. Update any outdated version numbers, tool references, ' +
+                    'or remove temporary notes that are no longer relevant.',
+                confidence,
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=stale-instructions.js.map

package/dist/stale-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-instructions.js","sourceRoot":"","sources":["../src/stale-instructions.ts"],"names":[],"mappings":"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"}

package/dist/suppression.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Inline suppression annotations for PromptCI.
+ *
+ * Annotation formats supported in any instruction file:
+ *
+ *   Section-scoped (suppresses the section containing or immediately following):
+ *     <!-- promptci-ignore: <category>
+ *          reason: <required explanation> -->
+ *
+ *   Range-scoped (suppresses everything between start and end markers):
+ *     <!-- promptci-ignore-start: <category>
+ *          reason: <required explanation> -->
+ *     ...content...
+ *     <!-- promptci-ignore-end -->
+ *
+ * Rules:
+ *   - `reason` is required. Missing reason → warning issue, issue is NOT suppressed.
+ *   - `category` must be a valid IssueCategory value or the special token `all`.
+ *   - Invalid category → warning issue, annotation does not suppress anything.
+ *   - An unpaired `promptci-ignore-start` (no matching end) → warning issue.
+ */
+import type { IssueCategory, InstructionFile, PromptCiIssue } from './types.js';
+export type SuppressionAnnotation = {
+    filePath: string;
+    category: IssueCategory | 'all';
+    reason: string;
+    startLine: number;
+    /** Last line (inclusive) within the suppression scope. */
+    endLine: number;
+    /** false = malformed annotation; still tracked so we can emit a warning issue. */
+    valid: boolean;
+    validationMessage?: string;
+};
+/**
+ * Parse all suppression annotations from a set of instruction files.
+ * Returns both valid and invalid annotations; call `buildValidationIssues`
+ * to surface invalid ones as actual scan issues.
+ */
+export declare function parseSuppressions(files: InstructionFile[]): SuppressionAnnotation[];
+/**
+ * Convert invalid suppression annotations into PromptCiIssue warning objects
+ * so they appear in the scan report and count against the health score.
+ * This ensures bad suppressions are visible rather than silently ignored.
+ */
+export declare function buildValidationIssues(annotations: SuppressionAnnotation[]): PromptCiIssue[];
+/**
+ * Partition a flat issues array into active and suppressed based on the
+ * provided annotations.
+ *
+ * Matching rules:
+ *   - Category match: annotation.category === 'all' OR === issue.category
+ *   - Location match (issue HAS locations): at least one location's filePath +
+ *     line range overlaps with the annotation's scope
+ *   - Location match (issue has EMPTY locations, e.g. agent_practices): match
+ *     by filePath alone (any of issue.filePaths matches annotation.filePath)
+ *
+ * Only valid annotations are used for matching; invalid ones emit warning issues
+ * that are never themselves suppressed.
+ */
+export declare function applySuppressions(issues: PromptCiIssue[], annotations: SuppressionAnnotation[]): {
+    active: PromptCiIssue[];
+    suppressed: PromptCiIssue[];
+};
+//# sourceMappingURL=suppression.d.ts.map

package/dist/suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppression.d.ts","sourceRoot":"","sources":["../src/suppression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAsB,aAAa,EAAE,MAAM,YAAY,CAAC;AA0BpG,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,GAAG,KAAK,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAuQF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,qBAAqB,EAAE,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,qBAAqB,EAAE,GACnC,aAAa,EAAE,CAiBjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EAAE,EACvB,WAAW,EAAE,qBAAqB,EAAE,GACnC;IAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAAC,UAAU,EAAE,aAAa,EAAE,CAAA;CAAE,CA4C1D"}