@promptci/core 0.0.1 → 0.2.0

package/dist/ai-config.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Shared support for the AI-setup config detectors (issue #23).
+ *
+ * These detectors audit the non-markdown surfaces of a 2026 AI setup — skills,
+ * subagents, hooks/permissions, MCP servers, and Cursor rules — against
+ * filesystem reality, the same way `command-validity` verifies documented
+ * commands. Everything here is deterministic and offline: no network, no LLM,
+ * identical output for identical input.
+ *
+ * This module holds the pieces every one of those detectors needs: a minimal
+ * YAML-frontmatter parser, root-relative path helpers that refuse to escape the
+ * repo, a stable file lister, and issue path normalization.
+ */
+import { resolveReadableWithinRoot, resolveWithinRoot } from './path-containment.js';
+import type { PromptCiIssue, ScanInput } from './types.js';
+/** Convert a filesystem path to forward-slash form for stable, portable output. */
+export declare function toPosix(p: string): string;
+export { resolveWithinRoot, resolveReadableWithinRoot };
+/** True when a repo-relative path exists and is a regular file. */
+export declare function isFileWithinRoot(repoRoot: string, relativePath: string): boolean;
+/** Read a repo-relative text file, or `undefined` if it is absent/unreadable. */
+export declare function readTextWithinRoot(repoRoot: string, relativePath: string): string | undefined;
+/**
+ * List files under `repoRoot` matching `patterns`, returned as repo-relative
+ * POSIX paths in sorted order. Dotfiles are included (these configs all live in
+ * dot-directories). Pass `ignore` to override the default discovery excludes.
+ */
+export declare function listFiles(repoRoot: string, patterns: string[], ignore?: string[]): string[];
+/** Pre-discovered config files per surface, as sorted repo-relative POSIX paths. */
+export type AiConfigFiles = {
+    /**
+     * Agent Skills audited structurally by the skills detector, in every
+     * supported skill location: `.claude/**\/SKILL.md`, `.agents/skills/**`,
+     * plugin `skills/*` and marketplace `plugins/*\/skills/*`. Subject to the
+     * size/binary guards.
+     */
+    skills: string[];
+    /**
+     * Every SKILL.md in the same locations as `skills`, read by the skill
+     * supply-chain scan. Honors include/exclude but NOT the size/binary guards:
+     * the supply-chain scan must see — and report — an oversized or NUL-bearing
+     * SKILL.md rather than silently lose the skill.
+     * Optional so hand-built contexts from older releases keep working.
+     */
+    allSkills?: string[];
+    /**
+     * Files bundled alongside a skill in `allSkills` (scripts, references,
+     * manifests): every file under the skill's directory except SKILL.md files,
+     * include/exclude applied, capped per skill BEFORE any file I/O. Read as text
+     * by the supply-chain scan — never executed. Optional (see `allSkills`).
+     */
+    skillFiles?: string[];
+    /** Bundled files dropped by the per-skill cap — reported, never silently lost. */
+    skillFilesOverCap?: string[];
+    /**
+     * Parts of a skill bundle the listing did not enumerate, so the supply-chain
+     * scan can name them: dependency/VCS directories, files an `include` config
+     * left out, and bundles too large to list.
+     */
+    skillBundleSkips?: SkillBundleSkip[];
+    /** Subagent definitions: `.claude/agents/**\/*.md`. */
+    agents: string[];
+    /** Claude Code settings: `.claude/settings.json` and `.claude/settings.local.json`. */
+    settings: string[];
+    /** Project MCP servers: `.mcp.json`. */
+    mcp: string[];
+    /** Cursor project rules: `.cursor/rules/**\/*.mdc`. */
+    cursorRules: string[];
+    /** GitHub Copilot per-file instructions: `.github/instructions/**\/*.md`. */
+    copilotInstructions: string[];
+};
+export type SkillBundleSkip = {
+    /** Repo-relative path: the skipped directory, or the skill directory for counts. */
+    path: string;
+    kind: 'dependency-dir' | 'include' | 'listing-limit';
+    /** Files affected, when known. */
+    count?: number;
+};
+/** An AiConfigFiles with every surface empty — for contexts built without discovery. */
+export declare function emptyAiConfigFiles(): AiConfigFiles;
+export declare function isSkillContainerDir(dir: string): boolean;
+/** Upper bound on bundled files read per skill, so one huge skill cannot stall a scan. */
+export declare const MAX_BUNDLED_FILES_PER_SKILL = 200;
+export declare function isPriorityBundleFile(rel: string): boolean;
+/**
+ * Discover the config files the ai_config detectors audit, honoring the same
+ * user-facing scan policy the markdown scanner applies: `exclude` patterns
+ * always remove files, an explicit `include` list bounds the scan scope (when
+ * unset, each surface's own globs are the scope — these configs are not in the
+ * scanner's DEFAULT_PATTERNS), and oversized or binary files are skipped.
+ *
+ * Called from buildRepoContext so detectors consume pre-discovered lists; a
+ * `--exclude` that silences a markdown finding for a file silences that file's
+ * ai_config findings too, instead of the detectors re-walking the repo with a
+ * policy of their own.
+ */
+export declare function discoverAiConfigFiles(repoRoot: string, policy?: Pick<ScanInput, 'include' | 'exclude'>): AiConfigFiles;
+/** Stable short hash for building per-finding IDs. */
+export declare function shortHash(input: string): string;
+/**
+ * Rewrite an issue's `filePaths`/`locations` from the detectors' repo-relative
+ * POSIX form to the absolute form the scanner stores in `InstructionFile.path`.
+ * Inline `promptci-ignore` suppressions match on exact path equality with the
+ * scanned file, so detector output must speak the same dialect or the
+ * `ai_config` category is unsuppressable. Display strings (titles, summaries,
+ * evidence) keep the friendly relative form; baseline fingerprints re-normalize
+ * absolute paths back to repo-relative, so they are unaffected.
+ */
+export declare function withScannerPaths(repoRoot: string, issues: PromptCiIssue[]): PromptCiIssue[];
+/** Extensions treated as invokable local scripts in hook/MCP command strings. */
+export declare const SCRIPT_EXT_RE: RegExp;
+/**
+ * 1-based line where `needle` first appears in `raw`, or 1 when not found.
+ * JSON sources store strings escaped, so a parsed command containing quotes or
+ * backslashes never appears verbatim — fall back to the JSON-escaped form
+ * before giving up on a real line number.
+ */
+export declare function lineOf(raw: string, needle: string): number;
+export type FrontmatterValue = string | string[] | boolean | number | null;
+export type Frontmatter = {
+    /** An opening `---` fence was present on the first content line. */
+    present: boolean;
+    /** A closing `---` (or `...`) fence was found. */
+    closed: boolean;
+    /** Top-level key → parsed value. Last write wins on duplicate keys. */
+    data: Record<string, FrontmatterValue>;
+    /** 1-based line of each top-level key (first occurrence). */
+    keyLines: Record<string, number>;
+    /** 1-based line of the closing fence, or -1 when unterminated. */
+    fenceEndLine: number;
+    /** 1-based first line of the document body after the closing fence. */
+    bodyStartLine: number;
+    /** Structural problems found while parsing (duplicate keys, etc.). */
+    errors: string[];
+};
+/**
+ * Parse a minimal YAML frontmatter block from the top of a document.
+ *
+ * Handles the subset these config files actually use: top-level `key: value`
+ * scalars, quoted strings, booleans/numbers, inline `[a, b]` sequences, block
+ * lists (`  - item`), and `|`/`>` block scalars. Nested mappings are recorded
+ * as errors rather than silently dropped, since none of the audited surfaces
+ * use them and a nested block is far more likely to be a mistake.
+ *
+ * This is deliberately not a full YAML engine — it exists to answer "is the
+ * frontmatter structurally sane and what are its top-level keys", not to load
+ * arbitrary YAML.
+ */
+export declare function parseFrontmatter(content: string): Frontmatter;
+/** Coerce a frontmatter value that may be a list or comma/newline string into a string[]. */
+export declare function asStringList(value: FrontmatterValue): string[];
+/** Fill in the defaults every ai_config finding shares. */
+export declare function aiConfigIssue(issue: Omit<PromptCiIssue, 'severity' | 'category' | 'confidence'> & Partial<Pick<PromptCiIssue, 'severity' | 'category' | 'confidence'>>): PromptCiIssue;
+/** Per-surface wording for the shared frontmatter-structure findings. */
+export type FrontmatterSurface = {
+    /** Id segment: findings get ids of the form `ai-config-<idPrefix>-<kind>-<hash>`. */
+    idPrefix: string;
+    /** Noun opening each finding title, e.g. 'Skill' or 'Cursor rule'. */
+    noun: string;
+    /** No-frontmatter summary tail: what a valid frontmatter block provides. */
+    why: string;
+    /** Recommendation for the no-frontmatter finding. */
+    recommendation: string;
+    /** Title override when the default `<noun> is missing YAML frontmatter` is wrong. */
+    noFrontmatterTitle?: string;
+    /** A missing block defaults to 'high' — Cursor rules soften it (metadata is optional-ish). */
+    noFrontmatterSeverity?: PromptCiIssue['severity'];
+    noFrontmatterConfidence?: number;
+};
+/**
+ * The three structural frontmatter findings every frontmatter-bearing surface
+ * (skills, subagents, Cursor rules) shares: block missing entirely, block never
+ * closed, and parse errors inside the block. When the block is missing the
+ * caller should skip its per-surface field checks, keyed off `fm.present` as
+ * before — this helper only builds the findings.
+ */
+export declare function frontmatterStructureIssues(filePath: string, content: string, fm: Frontmatter, surface: FrontmatterSurface): PromptCiIssue[];
+//# sourceMappingURL=ai-config.d.ts.map

package/dist/ai-config.d.ts.map

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