@promptci/core 0.0.1

package/dist/missing-context.js

@@ -0,0 +1,517 @@
+/**
+ * Missing-context detector for PromptCI.
+ *
+ * Flags files when they fail to mention project-specific keywords
+ * required for its detected type (Unity, TypeScript, etc.).
+ *
+ * The detector fires only when NONE of the required keywords are present,
+ * minimising false positives on repos that use custom tooling with different
+ * command names.
+ *
+ * All findings are heuristic — wording is cautious.
+ */
+import * as crypto from 'node:crypto';
+const PROJECT_TYPE_RULES = {
+    unity: {
+        // Any one of these signals Unity-specific coverage
+        keywords: ['unity', 'monobehaviour', 'gameobject', 'c#', 'unity editor', 'prefab'],
+        label: 'Unity',
+        minimumPresent: 1,
+    },
+    typescript: {
+        // Broad signals: build command, test runner, or tsconfig reference
+        keywords: [
+            'npm run build', 'pnpm run build', 'yarn run build', 'pnpm build', 'npm run test',
+            'npm test', 'pnpm test', 'yarn test', 'vitest', 'jest', 'typescript', 'tsconfig',
+            'tsc ', 'ts-node',
+        ],
+        label: 'TypeScript',
+        minimumPresent: 1,
+    },
+    dotnet: {
+        keywords: ['dotnet', '.sln', '.csproj', 'xunit', 'nunit', 'mstest', 'dotnet test', 'dotnet build'],
+        label: '.NET',
+        minimumPresent: 1,
+    },
+    nextjs: {
+        keywords: ['next.js', 'nextjs', 'next build', 'next dev', 'app router', 'pages router', 'vercel'],
+        label: 'Next.js',
+        minimumPresent: 1,
+    },
+    python: {
+        keywords: ['python', 'pip', 'poetry', 'venv', 'pytest', 'pyproject.toml'],
+        label: 'Python',
+        minimumPresent: 1,
+    },
+    go: {
+        keywords: ['golang', 'go.mod', 'go test', 'go build'],
+        label: 'Go',
+        minimumPresent: 1,
+    },
+    rust: {
+        keywords: ['rust', 'cargo', 'cargo build', 'cargo test', 'rustc'],
+        label: 'Rust',
+        minimumPresent: 1,
+    },
+};
+function issueId(key) {
+    const hash = crypto.createHash('sha1').update(key).digest('hex').slice(0, 12);
+    return `missing-context-${hash}`;
+}
+/**
+ * MC1: raw `String.includes` let bare single-word keywords match as a
+ * substring of an unrelated word — 'go' inside "algorithm"/"logo"/"django"/
+ * "good", 'pip' inside "pipeline", 'rust' inside "trust", 'unity' inside
+ * "community"/"opportunity" — making the "Missing X-specific context" check
+ * effectively unable to ever fire for those project types.
+ * Multi-word/punctuated keywords ("go test", "go.mod", "c#") are specific
+ * enough that plain substring matching is safe and stays unchanged; only a
+ * BARE alphanumeric word gets a `\b` word-boundary regex instead.
+ */
+function keywordPresent(content, keyword) {
+    const kw = keyword.toLowerCase();
+    if (/[^a-z0-9]/.test(kw))
+        return content.includes(kw);
+    return new RegExp(`\\b${kw}\\b`).test(content);
+}
+// ── Global checks (independent of project type) ───────────────────────────────
+/**
+ * MC2: extracts the CONTENT of closed fenced code blocks (``` or ~~~,
+ * matching fence char/length per CommonMark) so setup-command patterns can be
+ * tested against real block content only.
+ *
+ * The old approach used a single regex per pattern like
+ * `` ` ```[\s\S]*?command` `` (non-greedy but unbounded) — it could skip
+ * straight past the block's OWN closing fence and match a command mentioned
+ * arbitrarily later in the file, in prose or in a completely different code
+ * block. A tempered-dot rewrite (`` `(?:(?!```)[\s\S])*?` ``) looked like a
+ * fix but has the same underlying flaw for a file with an EVEN number of
+ * fences: the regex engine, unable to start a match at the true opening
+ * fence (blocked by the closing fence ahead), backtracks to start at the
+ * CLOSING fence instead and treats IT as a new opener — with no third fence
+ * left to bound it, everything after is fair game again. Regex alone can't
+ * reliably track "am I inside a block" across a variable number of fences;
+ * a real line-by-line scan (the same fence-tracking approach used 5x
+ * elsewhere in this codebase) does.
+ */
+function extractFencedBlockContents(content) {
+    const lines = content.split('\n');
+    const blocks = [];
+    let inBlock = false;
+    let fenceChar = null;
+    let fenceLen = 0;
+    let current = [];
+    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;
+                current = [];
+            }
+            continue;
+        }
+        const closeMatch = /^ {0,3}([`~]{3,})\s*$/.exec(line);
+        if (closeMatch && closeMatch[1][0] === fenceChar && closeMatch[1].length >= fenceLen) {
+            inBlock = false;
+            blocks.push(current.join('\n'));
+            fenceChar = null;
+            fenceLen = 0;
+            continue;
+        }
+        current.push(line);
+    }
+    // An unclosed trailing fence's partial content is intentionally excluded —
+    // this check only counts CONFIRMED, closed blocks as real documentation.
+    return blocks.join('\n');
+}
+/** Patterns that only count when found INSIDE a fenced code block's content. */
+const FENCED_SETUP_COMMAND_PATTERNS = [
+    /(npm|pnpm|yarn|uv)\s+(install|ci|run|sync|test|build|lint|add)/,
+    /dotnet\s+(build|test|restore)/,
+    /make\s+(build|test|install)/,
+    /cargo\s+(build|test)/,
+    /go\s+(build|test)/,
+    /uv\s+(run|sync|install|add)\b/,
+    // BUG-011: Python
+    /pip\s+(install|sync|download)\b/,
+    /python\s+-m\s+(venv|pytest|pip|build)\b/,
+    /python\s+setup\.py\b/,
+    /\bpytest\b/,
+];
+/**
+ * Patterns that signal a setup/validation command via inline backticks or
+ * plain prose — these are legitimate signals regardless of surrounding
+ * fence context, so they're tested against the FULL content, not just
+ * extracted block contents.
+ */
+const PROSE_SETUP_COMMAND_PATTERNS = [
+    // Inline backtick commands: `npm run build`, `pnpm test`, `uv sync`, etc.
+    /`(npm|pnpm|yarn)\s+(run\s+)?(build|test|lint|install)/,
+    /`(uv|dotnet)\s+(run|sync|install|test|build)/,
+    // BUG-011: Python — inline backtick
+    /`pip\s+(install|sync)/,
+    /`python\s+-m\s+(venv|pytest|pip)/,
+    /`pytest\b/,
+    // BUG-011: Go — inline backtick (fenced block pattern exists above but not inline)
+    /`go\s+(build|test|run|install)\b/,
+    // Plain prose with explicit command names
+    /(npm|pnpm|yarn)\s+run\s+(build|test|lint)/i,
+    /pnpm\s+(build|test|install|lint)/i,
+    /\buv\s+(run|sync|install|add)\b/i,
+    /\b(install|build|test)\s+(command|step|instruction)/i,
+    /how\s+to\s+(install|build|run|test)/i,
+    /getting\s+started/i,
+    // BUG-011: Python — plain prose
+    /\bpip\s+install\b/i,
+    /\bpython\s+-m\s+(venv|pytest|pip|build)\b/i,
+    /\bpytest\b/i,
+    /\bpython\s+setup\.py\b/i,
+    // BUG-011: Go — plain prose
+    /\bgo\s+(test|build|run)\s/i,
+];
+/**
+ * Patterns that signal security / secret-handling awareness in instructions.
+ * Use non-word-boundary suffixes so plurals match: "secrets", "credentials", etc.
+ */
+const SECURITY_PATTERNS = [
+    /\b(auth(entication|orization)?|rls|row.?level.?security)\b/i,
+    // Plurals: secrets, credentials, passwords, tokens, api keys
+    /\bsecrets?\b/i,
+    /\bcredentials?\b/i,
+    /\bpasswords?\b/i,
+    /\bapi.?keys?\b/i,
+    /\btokens?\b/i,
+    /\b(sanitize|sanitises?|injection)\b/i,
+    /\bvalidate\b.{0,50}\b(input|param)s?\b/i,
+    /\b(never\s+commit|do\s+not\s+commit|don.?t\s+commit).{0,50}\b(secret|key|credential)s?\b/i,
+    /\b(env(ironment)?\s+var|\.env)\b/i,
+    /\b(ssm|parameter\s+store|vault|keychain)\b/i,
+];
+function checkSetupCommands(files) {
+    const combined = files.map((f) => f.content).join('\n');
+    const fencedContent = extractFencedBlockContents(combined);
+    const hasSetup = FENCED_SETUP_COMMAND_PATTERNS.some((p) => p.test(fencedContent)) ||
+        PROSE_SETUP_COMMAND_PATTERNS.some((p) => p.test(combined));
+    if (hasSetup)
+        return null;
+    return {
+        id: issueId('missing-setup-commands'),
+        severity: 'warning',
+        category: 'missing_context',
+        title: 'No setup or validation commands found',
+        summary: 'No instruction file appears to document how to install dependencies, build, or run tests. ' +
+            'Agents cannot reliably set up or validate the project without this.',
+        filePaths: files.map((f) => f.path),
+        locations: [],
+        evidence: ['No install/build/test commands found in any instruction file.'],
+        recommendation: 'Add a "Setup" or "Getting Started" section with the exact commands to install, build, and test: ' +
+            'e.g. "pnpm install && pnpm build && pnpm test".',
+        confidence: 0.75,
+    };
+}
+/**
+ * BUG-007: Detect credential sections that describe storage but omit the security
+ * surface (token scopes, validation, expiry/rotation).
+ *
+ * Fires when:
+ *   1. At least one instruction file mentions credential/token/OAuth handling
+ *      (indicating there IS a credentials section)
+ *   2. But none of the files document scopes, token validation, or expiry handling
+ *
+ * This catches the pattern from GraftCLI: Security/Credentials sections that tell
+ * agents WHERE tokens are stored but not what scopes they need or how they expire.
+ */
+const CREDENTIAL_SECTION_PATTERNS = [
+    /\b(?:oauth|api\s*key|access\s*token|bearer\s*token|personal\s*access\s*token|github\s+token|gitlab\s+token)/i,
+    /\bPAT\b/,
+    /\b(?:store[sd]?\s+(?:in|to)\s+(?:keychain|config|file)|credential\s+storage|token\s+storage)/i,
+];
+const CREDENTIAL_SURFACE_PATTERNS = [
+    // Token scopes / permissions documented
+    /\b(?:scope[sd]?|permission[sd]?|required\s+scope|token\s+scope)/i,
+    // Validation / verification in any form (validate, validated, verifying, verified, etc.)
+    /\b(?:validat(?:e[sd]?|ion|ing)|verif(?:y|ied|ies|ication|ying))\b/i,
+    // Expiry or rotation documented
+    /\btoken\s+(?:expir[yi]|refresh|rotat)/i,
+    /\b(?:expir(?:y|ation|e[sd]?|ing)|refresh\s+token|token\s+rotation)\b/i,
+];
+function checkCredentialSurface(files) {
+    const combined = files.map((f) => f.content).join('\n');
+    const hasCredentialSection = CREDENTIAL_SECTION_PATTERNS.some((p) => p.test(combined));
+    if (!hasCredentialSection)
+        return null;
+    const hasSurfaceDoc = CREDENTIAL_SURFACE_PATTERNS.some((p) => p.test(combined));
+    if (hasSurfaceDoc)
+        return null;
+    return {
+        id: issueId('missing-credential-surface'),
+        severity: 'warning',
+        category: 'missing_context',
+        title: 'Credential section missing scope/validation/expiry documentation',
+        summary: 'Instruction files describe credential or token storage but do not document ' +
+            'required token scopes, how tokens are validated on first use, or how token ' +
+            'expiry and rotation are handled. Agents cannot safely handle auth edge cases ' +
+            'without this information.',
+        filePaths: files.map((f) => f.path),
+        locations: [],
+        evidence: ['Credential/token handling found, but no mention of scopes, validation, or expiry.'],
+        recommendation: 'Add documentation covering: (1) which OAuth scopes or API permissions are required, ' +
+            '(2) how tokens are validated on first use or after rotation, ' +
+            '(3) what happens when a token expires (error message, re-auth flow).',
+        confidence: 0.65,
+    };
+}
+function checkSecurityRules(files) {
+    const combined = files.map((f) => f.content).join('\n');
+    const hasSecurity = SECURITY_PATTERNS.some((p) => p.test(combined));
+    if (hasSecurity)
+        return null;
+    return {
+        id: issueId('missing-security-rules'),
+        severity: 'info',
+        category: 'missing_context',
+        title: 'No security or secret-handling rules found',
+        summary: 'No instruction file mentions authentication, secrets, API keys, RLS policies, or input validation. ' +
+            'Agents that handle user data or credentials benefit from explicit security guidelines.',
+        filePaths: files.map((f) => f.path),
+        locations: [],
+        evidence: ['No auth, secrets, RLS, or input validation keywords found.'],
+        recommendation: 'Add a security section covering: how auth is handled, where secrets live (.env, vault), ' +
+            'RLS/data-isolation requirements, and what agents must never commit or log.',
+        confidence: 0.65,
+    };
+}
+// ── BUG-008: Secret rotation / incident response check ───────────────────────
+/**
+ * Patterns indicating the project handles security-sensitive credentials or keys
+ * (JWT, TLS, API signing keys, etc.) that require rotation procedures.
+ */
+const SECURITY_SENSITIVE_PATTERNS = [
+    /\b(?:jwt|jwks|json\s+web\s+token)\b/i,
+    /\b(?:tls|ssl)\s+(?:cert(?:ificate)?|key)\b/i,
+    /\bsigning\s+key\b/i,
+    /\b(?:private|secret)\s+key\b/i,
+    /\bapi\s+(?:secret|signing)\b/i,
+    /\b(?:redis|kafka|broker)\s+(?:credential|password|secret|auth)\b/i,
+    /\bkey\s+(?:store|vault|ring)\b/i,
+];
+/**
+ * Patterns indicating rotation, key compromise response, or incident procedures
+ * are documented.
+ */
+const SECRET_ROTATION_PATTERNS = [
+    /\b(?:rotat(?:e[sd]?|ion|ing)|key\s+rotation|secret\s+rotation|credential\s+rotation)\b/i,
+    /\b(?:compromis(?:e[sd]?|ing)|key\s+compromise|breach)\b/i,
+    /\b(?:incident\s+response|security\s+incident)\b/i,
+    /\b(?:revo(?:ke[sd]?|cation)|invalidat(?:e[sd]?|ion))\b/i,
+    /\bwhat\s+to\s+do\s+(?:if|when)\s+.{0,40}(?:key|secret|credential|token)\b/i,
+    /\b(?:key|secret|token|cert(?:ificate)?)\s+expir(?:y|ation|es?|ing)\b/i,
+    /\brenew(?:ing|al|ed)?\s+(?:cert(?:ificate)?|key|token)\b/i,
+];
+function checkSecretRotation(files) {
+    const combined = files.map((f) => f.content).join('\n');
+    const hasSensitiveKeys = SECURITY_SENSITIVE_PATTERNS.some((p) => p.test(combined));
+    if (!hasSensitiveKeys)
+        return null;
+    const hasRotationDocs = SECRET_ROTATION_PATTERNS.some((p) => p.test(combined));
+    if (hasRotationDocs)
+        return null;
+    return {
+        id: issueId('missing-secret-rotation'),
+        severity: 'warning',
+        category: 'missing_context',
+        title: 'Security-sensitive project missing secret rotation / incident response guidance',
+        summary: 'Instruction files reference security-sensitive credentials or cryptographic keys (JWT, TLS, signing keys, etc.) ' +
+            'but do not document how to rotate them, what to do on suspected compromise, or how to handle expiry. ' +
+            'Agents cannot safely manage security events without this information.',
+        filePaths: files.map((f) => f.path),
+        locations: [],
+        evidence: [
+            'Security-sensitive key/credential references found, but no rotation, compromise, or incident-response procedure documented.',
+        ],
+        recommendation: 'Add a section covering: (1) how to rotate secrets or API keys, ' +
+            '(2) what to do if a key is suspected compromised (revoke, re-issue, notify), ' +
+            '(3) how certificate/token expiry is handled.',
+        confidence: 0.65,
+    };
+}
+// ── BUG-009: Environment variable list completeness check ─────────────────────
+/**
+ * Pattern for environment variable names: ALL_CAPS identifiers of ≥ 4 chars.
+ * Common enough to appear in any project that uses env vars.
+ */
+const ENV_VAR_NAME_RE = /\b([A-Z][A-Z0-9_]{3,})\b/g;
+/**
+ * Patterns that indicate a comprehensive env var section exists.
+ */
+const ENV_SECTION_PATTERNS = [
+    /\b(?:environment\s+variables?|env\s+vars?|required\s+(?:env(?:ironment)?\s+)?variables?)\b/i,
+    /\.env\.example\b/i,
+    /\benv(?:ironment)?\s+(?:setup|configuration|config)\b/i,
+    /\bconfigure\s+(?:your\s+)?environment\b/i,
+];
+/** Common all-caps words that are not environment variable names. */
+const ENV_VAR_STOP_WORDS = new Set([
+    'API', 'URL', 'HTTP', 'HTML', 'JSON', 'SQL', 'JWT', 'TLS', 'SSL', 'RLS',
+    'CRUD', 'REST', 'CORS', 'UUID', 'AUTH', 'NOTE', 'TODO', 'HACK', 'FIXME',
+    'WARN', 'INFO', 'NULL', 'TRUE', 'FALSE', 'NONE', 'VOID', 'ENUM', 'TYPE',
+    'TEST', 'PROD', 'DEV', 'DOCS', 'SKIP', 'PASS', 'FAIL', 'DONE', 'STOP',
+]);
+function checkEnvVarList(files) {
+    const combined = files.map((f) => f.content).join('\n');
+    const hasEnvSection = ENV_SECTION_PATTERNS.some((p) => p.test(combined));
+    if (hasEnvSection)
+        return null;
+    // Count distinct env-var-like names, excluding common false-positive caps words
+    const envVarNames = new Set();
+    let m;
+    const re = new RegExp(ENV_VAR_NAME_RE.source, ENV_VAR_NAME_RE.flags);
+    while ((m = re.exec(combined)) !== null) {
+        const name = m[1];
+        if (!ENV_VAR_STOP_WORDS.has(name) && name.includes('_')) {
+            // Must contain an underscore — distinguishes real env vars from acronyms
+            envVarNames.add(name);
+        }
+    }
+    // Only flag when ≥ 3 distinct env vars are named but there's no dedicated section
+    if (envVarNames.size < 3)
+        return null;
+    const examples = [...envVarNames].slice(0, 4).join(', ');
+    return {
+        id: issueId('missing-env-var-list'),
+        severity: 'info',
+        category: 'missing_context',
+        title: 'Environment variables referenced but no comprehensive list documented',
+        summary: `Instruction files mention ${envVarNames.size} environment variable name(s) (e.g. ${examples}) ` +
+            `but do not have a dedicated section listing all required variables. ` +
+            `Agents and new developers cannot reliably set up the project without a complete env var reference.`,
+        filePaths: files.map((f) => f.path),
+        locations: [],
+        evidence: [`${envVarNames.size} env-var-like names found: ${examples}…`],
+        recommendation: 'Add an "Environment Variables" or "Required Environment" section listing every required variable, ' +
+            'its purpose, and a safe example value. A .env.example file reference also satisfies this check.',
+        confidence: 0.6,
+    };
+}
+// ── BUG-010: Copilot topic-silence check ──────────────────────────────────────
+/**
+ * Topics that agents commonly need guidance on. Each entry defines:
+ *   - label:    Human-readable topic name (used in the issue title/summary)
+ *   - patterns: At least one must match in a file for it to "cover" the topic
+ *   - recommendation: Specific advice for the copilot-instructions.md author
+ *
+ * Only fires when at least one OTHER instruction file covers the topic —
+ * the point is that copilot-instructions.md is the lone silent outlier.
+ */
+const CROSS_FILE_TOPICS = [
+    {
+        label: 'file naming convention',
+        patterns: [
+            /\b(?:kebab-case|camelCase|camelcase|PascalCase|pascalcase|snake_case|naming\s+convention)\b/i,
+        ],
+        recommendation: 'Add a file naming rule to copilot-instructions.md (e.g. "Use kebab-case for all ' +
+            'files") so Copilot agents apply the same convention as the rest of the codebase.',
+    },
+];
+/**
+ * BUG-010: Detect when copilot-instructions.md is present but completely silent
+ * on a topic that is covered — and possibly in conflict — across other files.
+ *
+ * A Copilot agent reads only its own instruction file and has no guidance on the
+ * topic, even though human/Claude/Cursor agents are told what to do (or disagree
+ * about it).
+ */
+function checkCopilotTopicSilences(files) {
+    const normalizedPath = (file) => file.path.replace(/\\/g, '/').toLowerCase();
+    const isRootCopilotFile = (file) => {
+        const normalized = normalizedPath(file);
+        return normalized === '.github/copilot-instructions.md' ||
+            normalized.endsWith('/.github/copilot-instructions.md');
+    };
+    const isCopilotInstructionFile = (file) => file.fileType === 'copilot' || normalizedPath(file).includes('/.github/instructions/');
+    const copilotFile = files.find(isRootCopilotFile);
+    if (!copilotFile)
+        return [];
+    const copilotFiles = files.filter(isCopilotInstructionFile);
+    const otherFiles = files.filter((f) => !copilotFiles.includes(f));
+    if (otherFiles.length === 0)
+        return [];
+    const issues = [];
+    for (const { label, patterns, recommendation } of CROSS_FILE_TOPICS) {
+        const mentionedInOthers = otherFiles.some((f) => patterns.some((p) => p.test(f.content)));
+        if (!mentionedInOthers)
+            continue; // topic not documented anywhere — skip
+        const mentionedInCopilot = copilotFiles.some((f) => patterns.some((p) => p.test(f.content)));
+        if (mentionedInCopilot)
+            continue; // copilot already covers it — skip
+        issues.push({
+            id: issueId(`copilot-topic-silence:${label}`),
+            severity: 'info',
+            category: 'missing_context',
+            title: `copilot-instructions.md is silent on: ${label}`,
+            summary: `Other instruction files document the ${label}, but Copilot instruction files ` +
+                `do not mention it. Copilot agents will have no guidance on this topic.`,
+            filePaths: [copilotFile.path],
+            locations: [{ filePath: copilotFile.path }],
+            evidence: [
+                `"${label}" is documented in other instruction files but absent from Copilot instruction files.`,
+            ],
+            recommendation,
+            confidence: 0.6,
+        });
+    }
+    return issues;
+}
+export function detectMissingContext(files, projectType) {
+    const issues = [];
+    // ── Global checks (always run) ────────────────────────────────────────────
+    const setupIssue = checkSetupCommands(files);
+    if (setupIssue)
+        issues.push(setupIssue);
+    const securityIssue = checkSecurityRules(files);
+    if (securityIssue)
+        issues.push(securityIssue);
+    // BUG-007: credential section present but security surface (scopes/validation/expiry) absent
+    const credSurfaceIssue = checkCredentialSurface(files);
+    if (credSurfaceIssue)
+        issues.push(credSurfaceIssue);
+    // BUG-008: security-sensitive keys referenced but no rotation / incident-response docs
+    const secretRotationIssue = checkSecretRotation(files);
+    if (secretRotationIssue)
+        issues.push(secretRotationIssue);
+    // BUG-009: env vars referenced but no comprehensive env var list / section
+    const envVarIssue = checkEnvVarList(files);
+    if (envVarIssue)
+        issues.push(envVarIssue);
+    // BUG-010: copilot-instructions.md missing topics covered by other files
+    issues.push(...checkCopilotTopicSilences(files));
+    // ── Project-type-specific checks ──────────────────────────────────────────
+    if (projectType === 'auto' || projectType === 'unknown')
+        return issues;
+    const rules = PROJECT_TYPE_RULES[projectType];
+    if (!rules)
+        return issues;
+    const allContent = files.map((f) => f.content.toLowerCase()).join('\n');
+    const present = rules.keywords.filter((kw) => keywordPresent(allContent, kw));
+    if (present.length < rules.minimumPresent) {
+        const exampleKeywords = rules.keywords.slice(0, 3).join(', ');
+        issues.push({
+            id: issueId(projectType),
+            severity: 'warning',
+            category: 'missing_context',
+            title: `Missing ${rules.label}-specific context`,
+            summary: `This appears to be a ${rules.label} project, but the instruction files do not mention ` +
+                `any ${rules.label}-specific context (e.g. build commands, test runner, tooling).`,
+            filePaths: files.map((f) => f.path),
+            locations: [],
+            evidence: [`No keywords found matching: ${exampleKeywords}…`],
+            recommendation: `Add a section covering ${rules.label}-specific build commands, testing conventions, ` +
+                `and common project patterns so AI assistants have enough context to help effectively.`,
+            confidence: 0.75,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=missing-context.js.map

package/dist/missing-context.js.map

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

package/dist/native-tool-preference.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Native tool preference detector for PromptCI.
+ *
+ * Checks whether Claude-targeted instruction files guide agents to prefer
+ * Claude Code's built-in tools (Read, Grep, Glob) over equivalent Bash
+ * commands (cat, grep, find).
+ *
+ * Why it matters:
+ * - Built-in tools are faster (dedicated implementation, no subprocess overhead)
+ * - They use fewer tokens — Glob returns compact path lists, Grep returns
+ *   matched lines only, Read returns file content without shell noise
+ * - They bypass the PreToolUse hook entirely, so no RTK rewrite is needed
+ * - They respect Claude Code's permission model without separate Bash approval
+ *
+ * Only fires when Claude-targeted instruction files exist but contain no
+ * guidance about preferring these tools.
+ */
+import type { InstructionFile, PromptCiIssue } from './types.js';
+export declare function detectNativeToolPreference(files: InstructionFile[]): PromptCiIssue[];
+//# sourceMappingURL=native-tool-preference.d.ts.map

package/dist/native-tool-preference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-tool-preference.d.ts","sourceRoot":"","sources":["../src/native-tool-preference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgCjE,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAkDpF"}

package/dist/native-tool-preference.js

@@ -0,0 +1,94 @@
+/**
+ * Native tool preference detector for PromptCI.
+ *
+ * Checks whether Claude-targeted instruction files guide agents to prefer
+ * Claude Code's built-in tools (Read, Grep, Glob) over equivalent Bash
+ * commands (cat, grep, find).
+ *
+ * Why it matters:
+ * - Built-in tools are faster (dedicated implementation, no subprocess overhead)
+ * - They use fewer tokens — Glob returns compact path lists, Grep returns
+ *   matched lines only, Read returns file content without shell noise
+ * - They bypass the PreToolUse hook entirely, so no RTK rewrite is needed
+ * - They respect Claude Code's permission model without separate Bash approval
+ *
+ * Only fires when Claude-targeted instruction files exist but contain no
+ * guidance about preferring these tools.
+ */
+import * as path from 'node:path';
+// Positive signals — guidance about preferring native/built-in tools already exists.
+// Tool names (Read, Grep, Glob) are matched case-sensitively — they are always
+// capitalized when referring to Claude Code built-ins, unlike shell commands.
+const NATIVE_TOOL_SIGNALS = [
+    /\bRead\s+tool\b/,
+    /\bGrep\s+tool\b/,
+    /\bGlob\s+tool\b/,
+    /\b[Uu]se\s+Read\b/,
+    /\b[Uu]se\s+Grep\b/,
+    /\b[Uu]se\s+Glob\b/,
+    /\b[Pp]refer\s+Read\b/,
+    /\b[Pp]refer\s+Grep\b/,
+    /\b[Pp]refer\s+Glob\b/,
+    /\bdedicated\s+tools?\b.*\binstead\s+of\s+(cat|grep|find)\b/i,
+    /\b(avoid|instead\s+of|not)\b.*\b(cat|grep|find)\b.*\b(Read|Grep|Glob)\b/,
+    /\b(Read|Grep|Glob)\b.*\b(instead\s+of|not|avoid)\b.*\b(cat|grep|find)\b/i,
+    /built[- ]in\s+tools?\s+(over|instead\s+of|not|vs\.?)\s+(bash|shell|cat|grep|find)/i,
+];
+function isClaudeFile(file) {
+    const p = file.path.replace(/\\/g, '/').toLowerCase();
+    const base = path.basename(file.path).toLowerCase();
+    return (file.fileType === 'claude' ||
+        base === 'claude.md' ||
+        p.includes('/.claude/') ||
+        base === 'claude.local.md');
+}
+export function detectNativeToolPreference(files) {
+    const claudeFiles = files.filter(isClaudeFile);
+    if (claudeFiles.length === 0)
+        return [];
+    const combinedClaudeContent = claudeFiles.map((f) => f.content).join('\n');
+    const hasGuidance = NATIVE_TOOL_SIGNALS.some((pat) => pat.test(combinedClaudeContent));
+    if (hasGuidance)
+        return [];
+    // Also check all instruction files — guidance in AGENTS.md counts if Claude reads it.
+    const combinedAll = files.map((f) => f.content).join('\n');
+    const hasGuidanceAnywhere = NATIVE_TOOL_SIGNALS.some((pat) => pat.test(combinedAll));
+    if (hasGuidanceAnywhere)
+        return [];
+    return [
+        {
+            id: 'native-tool-preference-missing',
+            severity: 'info',
+            category: 'agent_practices',
+            title: 'No guidance to prefer built-in tools over Bash equivalents (Claude Code)',
+            summary: "Claude Code's built-in Read, Grep, and Glob tools are faster and more token-efficient " +
+                'than their Bash equivalents (cat/head/tail, grep/rg, find). Instructions that explicitly ' +
+                'prefer these tools reduce context noise and bypass the Bash permission prompt entirely. ' +
+                'No such guidance was found in Claude-targeted instruction files.',
+            filePaths: claudeFiles.map((f) => f.path),
+            locations: [],
+            evidence: [
+                `No Read/Grep/Glob preference guidance found in: ${claudeFiles.map((f) => path.basename(f.path)).join(', ')}.`,
+            ],
+            recommendation: 'Add a rule to Claude-targeted files instructing agents to prefer Read over cat/head/tail, ' +
+                'Grep over grep/rg, and Glob over find when working with local files. Reserve Bash for ' +
+                'operations that have no dedicated tool (e.g. git commands, running tests).',
+            fixRecipe: [
+                '## Tool Selection (Claude Code)',
+                '',
+                'Prefer dedicated tools over Bash for file operations — they are faster, more token-efficient,',
+                'and bypass the Bash permission prompt:',
+                '',
+                '- **File search**: Use `Glob` (not `find` or `ls`)',
+                '- **Content search**: Use `Grep` (not `grep` or `rg`)',
+                '- **Read files**: Use `Read` (not `cat`/`head`/`tail`)',
+                '',
+                'Reserve Bash for operations without a dedicated tool: git commands, running builds/tests,',
+                'package manager commands, and other shell-only operations.',
+            ].join('\n'),
+            confidence: 0.7,
+            impact: 'medium',
+        },
+    ];
+}
+//# sourceMappingURL=native-tool-preference.js.map