@promptci/core 0.0.1 → 0.2.0

package/dist/custom-rules.js

@@ -0,0 +1,303 @@
+/**
+ * Custom-rules engine (Decision D10) — a deterministic interpreter for
+ * `.promptci/custom-rules.json`. It lets a repo add its own instruction checks
+ * without shipping code, and those findings behave exactly like built-in ones:
+ * they carry `custom:*` ids, participate in suppression and the baseline/ratchet,
+ * and run identically in a local scan and the GitHub Action (both go through
+ * `buildRepoContext`).
+ *
+ * Four rule types:
+ *  - `forbiddenPattern`  — flag each file whose text matches a regex.
+ *  - `absentPattern`     — flag the repo when a required regex is absent from all targeted files.
+ *  - `requiredSection`   — flag the repo when a required heading appears in no targeted file.
+ *  - `crossFileConflict` — flag when a regex's captured value differs across files.
+ *
+ * Everything here is deterministic: no clock, network, or randomness. Malformed
+ * config is rejected with a clear, actionable error naming the offending key —
+ * never a crash or a silent skip.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import micromatch from 'micromatch';
+import { snippet } from './evidence.js';
+import { fileIdPath } from './finding-id.js';
+import { realPathWithinRoot } from './path-containment.js';
+export const CUSTOM_RULES_FILE = path.join('.promptci', 'custom-rules.json');
+export const CUSTOM_RULE_TYPES = [
+    'forbiddenPattern',
+    'absentPattern',
+    'requiredSection',
+    'crossFileConflict',
+];
+const VALID_SEVERITIES = ['info', 'warning', 'high', 'critical'];
+const VALID_REGEX_FLAGS = /^[gimsuy]*$/;
+// ── Validation ──────────────────────────────────────────────────────────────
+/** All validation failures throw this so callers can present them cleanly. */
+export class CustomRulesError extends Error {
+    constructor(message) {
+        super(`Invalid ${CUSTOM_RULES_FILE}: ${message}`);
+        this.name = 'CustomRulesError';
+    }
+}
+function requireString(obj, key, where) {
+    const value = obj[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new CustomRulesError(`${where} is missing a non-empty string "${key}".`);
+    }
+    return value;
+}
+function requireStringArray(value, key, where) {
+    if (!Array.isArray(value) || !value.every((v) => typeof v === 'string')) {
+        throw new CustomRulesError(`${where}: "${key}" must be an array of strings.`);
+    }
+    return value;
+}
+function validateRegex(pattern, flags, where) {
+    if (flags !== undefined && !VALID_REGEX_FLAGS.test(flags)) {
+        throw new CustomRulesError(`${where}: "flags" may only contain regex flags (gimsuy).`);
+    }
+    try {
+        void new RegExp(pattern, flags);
+    }
+    catch (err) {
+        throw new CustomRulesError(`${where}: "pattern" is not a valid regular expression: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Validate a parsed `.promptci/custom-rules.json` value into typed rules.
+ * Accepts either `{ "rules": [...] }` or a bare `[...]` array. Throws a
+ * {@link CustomRulesError} naming the offending key on any problem.
+ */
+export function parseCustomRules(raw) {
+    let rawRules;
+    if (Array.isArray(raw)) {
+        rawRules = raw;
+    }
+    else if (raw && typeof raw === 'object' && 'rules' in raw) {
+        rawRules = raw.rules;
+    }
+    else {
+        throw new CustomRulesError('top level must be an object with a "rules" array (or a bare array of rules).');
+    }
+    if (!Array.isArray(rawRules)) {
+        throw new CustomRulesError('"rules" must be an array.');
+    }
+    const rules = [];
+    const seenIds = new Set();
+    for (let i = 0; i < rawRules.length; i++) {
+        const entry = rawRules[i];
+        const where = `rule at index ${i}`;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw new CustomRulesError(`${where} must be an object.`);
+        }
+        const obj = entry;
+        const id = requireString(obj, 'id', where);
+        const ruleWhere = `rule "${id}"`;
+        if (seenIds.has(id)) {
+            throw new CustomRulesError(`${ruleWhere}: duplicate rule id (ids must be unique).`);
+        }
+        seenIds.add(id);
+        const type = requireString(obj, 'type', ruleWhere);
+        if (!CUSTOM_RULE_TYPES.includes(type)) {
+            throw new CustomRulesError(`${ruleWhere}: "type" must be one of ${CUSTOM_RULE_TYPES.join(', ')} (got "${type}").`);
+        }
+        const message = requireString(obj, 'message', ruleWhere);
+        let severity = 'warning';
+        if ('severity' in obj) {
+            if (typeof obj.severity !== 'string' || !VALID_SEVERITIES.includes(obj.severity)) {
+                throw new CustomRulesError(`${ruleWhere}: "severity" must be one of ${VALID_SEVERITIES.join(', ')}.`);
+            }
+            severity = obj.severity;
+        }
+        const rule = { id, type: type, message, severity };
+        if ('files' in obj)
+            rule.files = requireStringArray(obj.files, 'files', ruleWhere);
+        if ('flags' in obj) {
+            if (typeof obj.flags !== 'string') {
+                throw new CustomRulesError(`${ruleWhere}: "flags" must be a string.`);
+            }
+            rule.flags = obj.flags;
+        }
+        if (type === 'requiredSection') {
+            rule.heading = requireString(obj, 'heading', ruleWhere);
+        }
+        else {
+            // pattern-based types
+            rule.pattern = requireString(obj, 'pattern', ruleWhere);
+            validateRegex(rule.pattern, rule.flags, ruleWhere);
+        }
+        rules.push(rule);
+    }
+    return rules;
+}
+/**
+ * Load and validate `.promptci/custom-rules.json` from a repo root. A missing
+ * file yields no rules; invalid JSON or an invalid schema throws a
+ * {@link CustomRulesError} with an actionable message.
+ */
+export async function loadCustomRules(repoRoot) {
+    const filePath = path.join(repoRoot, CUSTOM_RULES_FILE);
+    // A config committed as a symlink to a file outside the repo is not read.
+    if (!realPathWithinRoot(repoRoot, filePath))
+        return [];
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CustomRulesError('file is not valid JSON.');
+    }
+    return parseCustomRules(parsed);
+}
+// ── Interpreter ─────────────────────────────────────────────────────────────
+function shortHash(value) {
+    return crypto.createHash('sha1').update(value).digest('hex').slice(0, 12);
+}
+/** 1-based line number of a character offset within `content`. */
+function lineOfOffset(content, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === '\n')
+            line++;
+    }
+    return line;
+}
+/** Files a rule targets: all instruction files, or those matching its globs. */
+function targetedFiles(files, rule, repoRoot) {
+    if (!rule.files || rule.files.length === 0)
+        return files;
+    return files.filter((f) => {
+        const rel = path.relative(repoRoot, f.path).replace(/\\/g, '/');
+        return micromatch.isMatch(rel, rule.files, { dot: true });
+    });
+}
+function freshRegex(rule) {
+    // A fresh instance per use so a shared `g` flag never leaks lastIndex.
+    return new RegExp(rule.pattern, rule.flags);
+}
+function baseIssue(rule) {
+    return { severity: rule.severity, category: 'custom', confidence: 1.0, tags: ['custom-rule'] };
+}
+function runForbiddenPattern(files, rule) {
+    const issues = [];
+    for (const file of files) {
+        const match = freshRegex(rule).exec(file.content);
+        if (!match)
+            continue;
+        const line = lineOfOffset(file.content, match.index);
+        issues.push({
+            id: `custom:${rule.id}:${shortHash(fileIdPath(file))}`,
+            ...baseIssue(rule),
+            title: rule.message,
+            summary: `Custom rule "${rule.id}": a forbidden pattern was found in this file.`,
+            filePaths: [file.path],
+            locations: [{ filePath: file.path, startLine: line, endLine: line }],
+            evidence: [`Matched text: "${snippet(match[0], 120)}" (line ${line})`],
+            recommendation: `Remove or revise the flagged content to satisfy custom rule "${rule.id}".`,
+        });
+    }
+    return issues;
+}
+function runAbsentPattern(files, rule) {
+    const present = files.some((f) => freshRegex(rule).test(f.content));
+    if (present)
+        return [];
+    return [
+        {
+            id: `custom:${rule.id}`,
+            ...baseIssue(rule),
+            title: rule.message,
+            summary: `Custom rule "${rule.id}": a required pattern is absent from all checked instruction files.`,
+            filePaths: files.map((f) => f.path),
+            locations: files.map((f) => ({ filePath: f.path })),
+            evidence: [`Required pattern was not found in any of ${files.length} checked file(s).`],
+            recommendation: `Add content matching custom rule "${rule.id}" to one of the instruction files.`,
+        },
+    ];
+}
+function normalizeHeading(h) {
+    return h.toLowerCase().replace(/^#+\s*/, '').replace(/\s+/g, ' ').trim();
+}
+function runRequiredSection(files, rule) {
+    const wanted = normalizeHeading(rule.heading);
+    const found = files.some((f) => f.sections.some((s) => s.heading !== undefined && normalizeHeading(s.heading).includes(wanted)));
+    if (found)
+        return [];
+    return [
+        {
+            id: `custom:${rule.id}`,
+            ...baseIssue(rule),
+            title: rule.message,
+            summary: `Custom rule "${rule.id}": a required section heading ("${rule.heading}") is missing from all checked files.`,
+            filePaths: files.map((f) => f.path),
+            locations: files.map((f) => ({ filePath: f.path })),
+            evidence: [`No section heading matching "${rule.heading}" was found in ${files.length} checked file(s).`],
+            recommendation: `Add a "${rule.heading}" section to one of the instruction files to satisfy custom rule "${rule.id}".`,
+        },
+    ];
+}
+function runCrossFileConflict(files, rule) {
+    // value → the files (and the line) where it was captured.
+    const byValue = new Map();
+    for (const file of files) {
+        const match = freshRegex(rule).exec(file.content);
+        if (!match)
+            continue;
+        // Prefer the first capture group when present, else the whole match.
+        const value = (match[1] ?? match[0]).trim();
+        const line = lineOfOffset(file.content, match.index);
+        const list = byValue.get(value) ?? [];
+        list.push({ filePath: file.path, line });
+        byValue.set(value, list);
+    }
+    if (byValue.size < 2)
+        return [];
+    const filePaths = [...new Set([...byValue.values()].flat().map((v) => v.filePath))];
+    const locations = [...byValue.values()].flat().map((v) => ({ filePath: v.filePath, startLine: v.line, endLine: v.line }));
+    const evidence = [...byValue.entries()].map(([value, where]) => `"${snippet(value, 60)}" in ${where.map((w) => path.basename(w.filePath)).join(', ')}`);
+    return [
+        {
+            id: `custom:${rule.id}`,
+            ...baseIssue(rule),
+            title: rule.message,
+            summary: `Custom rule "${rule.id}": the tracked value differs across files (${byValue.size} distinct values).`,
+            filePaths,
+            locations,
+            evidence,
+            recommendation: `Reconcile the conflicting values so custom rule "${rule.id}" sees a single consistent value.`,
+        },
+    ];
+}
+/** Run all validated custom rules over the scanned instruction files. */
+export function runCustomRules(files, rules, repoRoot) {
+    const issues = [];
+    for (const rule of rules) {
+        const scoped = targetedFiles(files, rule, repoRoot);
+        switch (rule.type) {
+            case 'forbiddenPattern':
+                issues.push(...runForbiddenPattern(scoped, rule));
+                break;
+            case 'absentPattern':
+                issues.push(...runAbsentPattern(scoped, rule));
+                break;
+            case 'requiredSection':
+                issues.push(...runRequiredSection(scoped, rule));
+                break;
+            case 'crossFileConflict':
+                issues.push(...runCrossFileConflict(scoped, rule));
+                break;
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=custom-rules.js.map

package/dist/custom-rules.js.map

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

package/dist/dead-references.d.ts

@@ -7,13 +7,19 @@
  *   - Reference-style links: [text][ref] with a `[ref]: path` definition
  *   - @-file refs:     @AGENTS.md  |  @docs/guide.md
  *
+ *   - Directory / extension-less paths (pcic-2b6.8): links like
+ *     [api](./src/api/) and code spans like `apps/admin/` or `src/payments`
+ *
  * External URLs (http/https), anchor-only links (#section), and mailto:
- * are always skipped. Only paths with a recognisable file extension are
- * checked to avoid false-positiving on badge shields, npm package names, etc.
+ * are always skipped. File paths need a recognisable extension; a directory or
+ * extension-less path in a code span is only checked when its FIRST segment
+ * exists in the repository (so `owner/repo`, `origin/main`, `@scope/pkg` and
+ * paths describing some other project stay silent).
  *
  * Findings are heuristic — wording is intentionally cautious.
  */
 import type { InstructionFile, PromptCiIssue } from './types.js';
+export declare function isHomeRooted(ref: string): boolean;
 /**
  * Detect broken file references across all instruction files.
  *

package/dist/dead-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dead-references.d.ts","sourceRoot":"","sources":["../src/dead-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA0jBjE;;;;;GAKG;AACH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,EAAE,EACxB,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE,CAgGjB"}
+{"version":3,"file":"dead-references.d.ts","sourceRoot":"","sources":["../src/dead-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgTjE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAigBD;;;;;GAKG;AACH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,EAAE,EACxB,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE,CAuGjB"}