@promptci/core 0.0.1 → 0.2.0

package/dist/negative-instructions.js

@@ -0,0 +1,169 @@
+/**
+ * Negative-instruction overload detector (FEAT-010).
+ *
+ * Models follow positive directives ("use const") more reliably than
+ * prohibitions ("don't use var"). A file whose directive sentences are
+ * overwhelmingly phrased as prohibitions is harder to follow than the same
+ * guidance framed positively.
+ *
+ * Heuristic: split the file into candidate sentences, classify each as a
+ * positive directive, a negative directive, or neither, and — when there are
+ * enough directives to be meaningful — flag files where more than 40% of the
+ * directives are negative. Info severity only; the wording is deliberately
+ * cautious and the recommendation offers a positive-rewrite hint.
+ *
+ * Deterministic and rule-based: no clock, network, or randomness.
+ */
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { INSTRUCTION_FILE_TYPES } from './types.js';
+import { snippet } from './evidence.js';
+import { fileIdPath } from './finding-id.js';
+/** Persistent, always-loaded instruction files this detector applies to. */
+const TARGET_FILE_TYPES = INSTRUCTION_FILE_TYPES;
+/**
+ * A sentence is a NEGATIVE directive when it contains one of these prohibition
+ * markers. Negative markers take precedence over positive ones, so "always
+ * avoid mutation" counts as negative — its operative instruction is a
+ * prohibition.
+ */
+const NEGATIVE_MARKERS = [
+    // Second-person imperative prohibitions only. Third-person "does not" /
+    // "doesn't" is descriptive narration ("this file does not repeat it"), not a
+    // directive, so it is deliberately excluded to avoid inflating the count.
+    /\bdo\s+not\b/i,
+    /\bdon['’]?t\b/i,
+    /\bnever\b/i,
+    /\bavoid\b/i,
+    /\brefrain\s+from\b/i,
+    /\bmust\s+not\b/i,
+    /\bmustn['’]?t\b/i,
+    /\bshould\s+not\b/i,
+    /\bshouldn['’]?t\b/i,
+    /\bcannot\b/i,
+    /\bcan['’]?t\b/i,
+    /\bwon['’]?t\b/i,
+    /\bno\s+longer\b/i,
+];
+/**
+ * A sentence is a POSITIVE directive when it starts with an imperative verb or
+ * carries a positive modal ("must"/"should"/"always" not already caught as
+ * negative above). This intentionally under-counts rather than over-counts:
+ * only clearly directive sentences enter the denominator.
+ */
+const POSITIVE_IMPERATIVE_START = /^(use|always|prefer|ensure|make\s+sure|keep|run|write|add|follow|call|set|return|check|verify|read|ask|include|place|put|store|document|test|update|create|define|import|export|name|group|split|choose|pick|apply|treat|surface|confirm|report|explain|favor|favour|default\s+to|stick\s+to|remember\s+to|be\s+sure\s+to)\b/i;
+const POSITIVE_MODAL = /\b(must|should|always|shall)\b/i;
+const MIN_DIRECTIVES = 8; // below this the ratio is too noisy to be meaningful
+const NEGATIVE_RATIO_THRESHOLD = 0.4; // > 40% negative → finding
+/** Strip a leading markdown list bullet / ordered-list marker / heading hash. */
+function stripLeadingMarkers(line) {
+    return line
+        .replace(/^\s*#{1,6}\s+/, '')
+        .replace(/^\s*[-*+]\s+/, '')
+        .replace(/^\s*\d+[.)]\s+/, '')
+        .replace(/^\s*>\s+/, '')
+        .trim();
+}
+/**
+ * Strip leading markdown emphasis (`**bold**`, `*italic*`, `` `code` ``) so the
+ * operative verb is visible to the imperative test — otherwise "**Report** ..."
+ * hides the "Report" that makes the sentence a positive directive.
+ */
+function stripLeadingEmphasis(text) {
+    return text.replace(/^[*_`]+/, '').trimStart();
+}
+/**
+ * Split file content into candidate directive sentences. Fenced code blocks are
+ * dropped (a bash comment is not an instruction sentence). Each non-blank line
+ * is stripped of list/heading markers, then split on sentence terminators so a
+ * line holding two clauses is counted as two.
+ */
+export function splitSentences(content) {
+    const lines = content.split(/\r?\n/);
+    const sentences = [];
+    let inFence = false;
+    for (const raw of lines) {
+        const fenceToggle = /^\s*(```|~~~)/.test(raw);
+        if (fenceToggle) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const cleaned = stripLeadingMarkers(raw);
+        if (!cleaned)
+            continue;
+        for (const part of cleaned.split(/(?<=[.!?])\s+/)) {
+            const trimmed = part.trim();
+            // Require a few words so table cells / fragments don't count as sentences.
+            if (trimmed.split(/\s+/).length >= 3)
+                sentences.push(trimmed);
+        }
+    }
+    return sentences;
+}
+function classify(sentence) {
+    const lead = stripLeadingEmphasis(sentence);
+    // The LEADING imperative governs: a positively-framed instruction that also
+    // mentions a prohibition ("Keep diffs focused; do not refactor unrelated
+    // code") is a positive directive, not a negative one. Only sentences whose
+    // primary verb is not a positive imperative fall through to the prohibition
+    // markers.
+    if (POSITIVE_IMPERATIVE_START.test(lead))
+        return 'positive';
+    for (const re of NEGATIVE_MARKERS) {
+        if (re.test(sentence))
+            return 'negative';
+    }
+    if (POSITIVE_MODAL.test(sentence))
+        return 'positive';
+    return 'none';
+}
+function issueId(filePath) {
+    const hash = crypto.createHash('sha1').update(`negative-overload:${filePath}`).digest('hex').slice(0, 12);
+    return `negative-overload-${hash}`;
+}
+export function detectNegativeInstructionOverload(files) {
+    const issues = [];
+    for (const file of files) {
+        if (!TARGET_FILE_TYPES.has(file.fileType))
+            continue;
+        const sentences = splitSentences(file.content);
+        const negatives = [];
+        let positiveCount = 0;
+        for (const sentence of sentences) {
+            const kind = classify(sentence);
+            if (kind === 'negative')
+                negatives.push(sentence);
+            else if (kind === 'positive')
+                positiveCount++;
+        }
+        const total = negatives.length + positiveCount;
+        if (total < MIN_DIRECTIVES)
+            continue;
+        const ratio = negatives.length / total;
+        if (ratio <= NEGATIVE_RATIO_THRESHOLD)
+            continue;
+        const fileName = path.basename(file.path);
+        const pct = Math.round(ratio * 100);
+        const examples = negatives.slice(0, 3).map((s) => snippet(s, 100));
+        issues.push({
+            id: issueId(fileIdPath(file)),
+            severity: 'info',
+            category: 'agent_practices',
+            title: 'High proportion of negative instructions',
+            summary: `About ${pct}% of the directive sentences in "${fileName}" are phrased as prohibitions ` +
+                `(${negatives.length} of ${total}). Models tend to follow positive directives more ` +
+                `reliably than prohibitions, so heavily negative guidance can be harder to apply.`,
+            filePaths: [file.path],
+            locations: [],
+            evidence: examples.map((e) => `Negative directive: "${e}"`),
+            recommendation: 'Where practical, rephrase prohibitions as positive directives — e.g. instead of ' +
+                '"don\'t use var", write "always use const or let". Keep prohibitions for the cases ' +
+                'where no positive form is possible.',
+            confidence: 0.5,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=negative-instructions.js.map

package/dist/negative-instructions.js.map

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

package/dist/path-containment.d.ts

@@ -0,0 +1,41 @@
+/**
+ * True when `candidatePath` resolves to `root` itself or a descendant of it.
+ * Both arguments are resolved to absolute form first, so either may be relative.
+ */
+export declare function isWithinRoot(root: string, candidatePath: string): boolean;
+/**
+ * Resolve `candidatePath` — treated as relative to `root` unless it is itself
+ * absolute — and return the absolute path when it stays within `root`, or
+ * `null` when it escapes (via `..`, an absolute path, or a different drive).
+ */
+export declare function resolveWithinRoot(root: string, candidatePath: string): string | null;
+/** The canonical real path (symlinks resolved), or null when it does not exist. */
+export declare function realPath(p: string): string | null;
+/**
+ * True unless `absPath` exists and resolves — through a symlinked file or any
+ * symlinked directory on its path — to a location outside `root`. The lexical
+ * checks above cannot see a symlink: a committed `CLAUDE.md -> /etc/passwd`
+ * or `package.json -> ~/.npmrc` passes them and is then read through. In-repo
+ * symlinks stay readable. A path that does not exist (or a dangling link) has
+ * nothing to read through, so it is left to the caller's own read to fail.
+ */
+export declare function realPathWithinRoot(root: string, absPath: string): boolean;
+/**
+ * {@link resolveWithinRoot} for paths about to be READ: additionally `null`
+ * when the target is a symlink (or sits under a symlinked directory) whose
+ * real path escapes `root`.
+ */
+export declare function resolveReadableWithinRoot(root: string, candidatePath: string): string | null;
+/**
+ * True when WRITING `target` stays inside `root`. The mirror of the read
+ * policy: a path inside the root must not reach outside through a symlink on
+ * any component that already exists (a `.promptci` committed as a link to
+ * `/etc`, a `latest.md` linked to `~/.bashrc`), including a dangling link whose
+ * target a write would create outside. The nearest existing ancestor is
+ * checked, so a not-yet-created file is judged by the directory it would land in.
+ *
+ * A target that is lexically OUTSIDE the root is the caller's explicit choice
+ * (`--output /tmp/report.md`) and is allowed.
+ */
+export declare function writeTargetWithinRoot(root: string, target: string): boolean;
+//# sourceMappingURL=path-containment.d.ts.map

package/dist/path-containment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-containment.d.ts","sourceRoot":"","sources":["../src/path-containment.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAYzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUpF;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOjD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKzE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAgB3E"}

package/dist/path-containment.js

@@ -0,0 +1,123 @@
+/**
+ * The one path-containment check for the whole toolchain.
+ *
+ * Every place that resolves an externally-influenced path (a config value, an
+ * LLM-proposed edit target, a fix's file path) must confirm the result stays
+ * inside the repo/target root before touching the filesystem. This module is
+ * the single, tested implementation those checks share.
+ *
+ * The naive guard this replaces — `resolved.startsWith(root)` — is wrong two
+ * ways:
+ *   - **Sibling prefix.** `/repo-evil` starts with `/repo`, so a sibling
+ *     directory whose name merely shares a prefix reads as "contained".
+ *   - **Separator / drive blind spots.** On Windows a raw string prefix ignores
+ *     the path separator boundary and cross-drive absolutes.
+ *
+ * Comparing the *relative* path from the root sidesteps both: a contained path
+ * yields `''` (the root itself) or a forward walk with no leading `..`; any
+ * escape yields a leading `..` segment or an absolute path (a different drive).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * True when `candidatePath` resolves to `root` itself or a descendant of it.
+ * Both arguments are resolved to absolute form first, so either may be relative.
+ */
+export function isWithinRoot(root, candidatePath) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(candidatePath);
+    const rel = path.relative(resolvedRoot, resolved);
+    // '' is the root itself. A genuine escape is exactly '..' or begins with
+    // '..<sep>' (a child literally named e.g. '..foo' is NOT an escape), or is
+    // absolute — which path.relative only returns when the target is on a
+    // different Windows drive and cannot be reached by walking up.
+    return (rel === '' ||
+        (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)));
+}
+/**
+ * Resolve `candidatePath` — treated as relative to `root` unless it is itself
+ * absolute — and return the absolute path when it stays within `root`, or
+ * `null` when it escapes (via `..`, an absolute path, or a different drive).
+ */
+export function resolveWithinRoot(root, candidatePath) {
+    try {
+        const resolvedRoot = path.resolve(root);
+        const resolved = path.isAbsolute(candidatePath)
+            ? path.resolve(candidatePath)
+            : path.resolve(resolvedRoot, candidatePath);
+        return isWithinRoot(resolvedRoot, resolved) ? resolved : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The canonical real path (symlinks resolved), or null when it does not exist. */
+export function realPath(p) {
+    try {
+        const real = fs.realpathSync.native(p);
+        return typeof real === 'string' ? real : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True unless `absPath` exists and resolves — through a symlinked file or any
+ * symlinked directory on its path — to a location outside `root`. The lexical
+ * checks above cannot see a symlink: a committed `CLAUDE.md -> /etc/passwd`
+ * or `package.json -> ~/.npmrc` passes them and is then read through. In-repo
+ * symlinks stay readable. A path that does not exist (or a dangling link) has
+ * nothing to read through, so it is left to the caller's own read to fail.
+ */
+export function realPathWithinRoot(root, absPath) {
+    const real = realPath(absPath);
+    if (real === null)
+        return true;
+    const realRoot = realPath(root) ?? path.resolve(root);
+    return isWithinRoot(realRoot, real);
+}
+/**
+ * {@link resolveWithinRoot} for paths about to be READ: additionally `null`
+ * when the target is a symlink (or sits under a symlinked directory) whose
+ * real path escapes `root`.
+ */
+export function resolveReadableWithinRoot(root, candidatePath) {
+    const resolved = resolveWithinRoot(root, candidatePath);
+    if (resolved === null)
+        return null;
+    return realPathWithinRoot(root, resolved) ? resolved : null;
+}
+/**
+ * True when WRITING `target` stays inside `root`. The mirror of the read
+ * policy: a path inside the root must not reach outside through a symlink on
+ * any component that already exists (a `.promptci` committed as a link to
+ * `/etc`, a `latest.md` linked to `~/.bashrc`), including a dangling link whose
+ * target a write would create outside. The nearest existing ancestor is
+ * checked, so a not-yet-created file is judged by the directory it would land in.
+ *
+ * A target that is lexically OUTSIDE the root is the caller's explicit choice
+ * (`--output /tmp/report.md`) and is allowed.
+ */
+export function writeTargetWithinRoot(root, target) {
+    const resolved = path.resolve(target);
+    if (!isWithinRoot(root, resolved))
+        return true;
+    let probe = resolved;
+    for (;;) {
+        if (realPath(probe) !== null)
+            return realPathWithinRoot(root, probe);
+        try {
+            // lstat succeeding while realpath failed: a dangling symlink, whose target a write would create.
+            if (fs.lstatSync(probe).isSymbolicLink())
+                return false;
+        }
+        catch {
+            // does not exist: look at its parent
+        }
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            return true;
+        probe = parent;
+    }
+}
+//# sourceMappingURL=path-containment.js.map

package/dist/path-containment.js.map

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

package/dist/project-type.d.ts

@@ -1,7 +1,12 @@
 import type { InstructionFile, ProjectType } from './types.js';
 /**
  * Detect the primary project type for a repo at repoRoot.
- * Detection order: nextjs → typescript → unity → dotnet → unknown
+ * Detection order: nextjs → unity → dotnet → typescript → python → go → rust → unknown
+ *
+ * Unity/.NET probes run before the package.json→typescript branch: Unity and .NET
+ * repos commonly carry a root package.json for JS tooling (husky, prettier), so the
+ * bare-package.json check must not shadow their more specific markers. This matches
+ * the unity-before-typescript ordering in detectProjectTypeFromContent.
  */
 export declare function detectProjectType(repoRoot: string): Promise<ProjectType>;
 /**
@@ -9,7 +14,12 @@ export declare function detectProjectType(repoRoot: string): Promise<ProjectType
  * scan returns 'unknown' (e.g. repos that only contain instruction files, no source).
  * Checks the combined content of all scanned instruction files for strong signals.
  *
- * Detection order: nextjs → unity → typescript → dotnet → python → go → rust → unknown
+ * Detection order: nextjs → unity → dotnet → typescript → python → go → rust → unknown
+ *
+ * .NET is checked before typescript for the same reason as in the file-system
+ * probe above: .NET repos commonly mention JS tooling (pnpm, npm run, jest) in
+ * their instructions, so the broader typescript signals must not shadow the
+ * more specific .NET ones.
  */
 export declare function detectProjectTypeFromContent(files: InstructionFile[]): ProjectType;
 //# sourceMappingURL=project-type.d.ts.map

package/dist/project-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-type.d.ts","sourceRoot":"","sources":["../src/project-type.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAoB/D;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4D9E;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,WAAW,CA0BlF"}
+{"version":3,"file":"project-type.d.ts","sourceRoot":"","sources":["../src/project-type.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAoB/D;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+D9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,WAAW,CA0BlF"}

package/dist/project-type.js

@@ -21,7 +21,12 @@ async function dirExists(p) {
 }
 /**
  * Detect the primary project type for a repo at repoRoot.
- * Detection order: nextjs → typescript → unity → dotnet → unknown
+ * Detection order: nextjs → unity → dotnet → typescript → python → go → rust → unknown
+ *
+ * Unity/.NET probes run before the package.json→typescript branch: Unity and .NET
+ * repos commonly carry a root package.json for JS tooling (husky, prettier), so the
+ * bare-package.json check must not shadow their more specific markers. This matches
+ * the unity-before-typescript ordering in detectProjectTypeFromContent.
  */
 export async function detectProjectType(repoRoot) {
     const root = path.resolve(repoRoot);
@@ -42,19 +47,17 @@ export async function detectProjectType(repoRoot) {
         if (hasApp || hasPages)
             return 'nextjs';
     }
-    // ── TypeScript ───────────────────────────────────────────────────────────
-    // package.json or tsconfig.json present
-    const hasTsConfig = await exists(path.join(root, 'tsconfig.json'));
-    if (hasPkgJson || hasTsConfig)
-        return 'typescript';
     // ── Unity ────────────────────────────────────────────────────────────────
-    // Assets/ directory AND ProjectSettings/ProjectVersion.txt both exist
+    // Assets/ directory AND ProjectSettings/ProjectVersion.txt both exist.
+    // Checked before the package.json→typescript branch so a Unity repo with a
+    // root package.json is not misclassified as typescript.
     const hasAssets = await dirExists(path.join(root, 'Assets'));
     const hasProjectVersion = await exists(path.join(root, 'ProjectSettings', 'ProjectVersion.txt'));
     if (hasAssets && hasProjectVersion)
         return 'unity';
     // ── .NET ─────────────────────────────────────────────────────────────────
-    // any .sln or .csproj file at repo root level
+    // any .sln or .csproj file at repo root level. Also checked before the
+    // typescript branch for the same reason (JS tooling drops a package.json).
     const dotnetFiles = await fg(['*.sln', '*.csproj'], {
         cwd: root,
         dot: false,
@@ -63,6 +66,11 @@ export async function detectProjectType(repoRoot) {
     });
     if (dotnetFiles.length > 0)
         return 'dotnet';
+    // ── TypeScript ───────────────────────────────────────────────────────────
+    // package.json or tsconfig.json present
+    const hasTsConfig = await exists(path.join(root, 'tsconfig.json'));
+    if (hasPkgJson || hasTsConfig)
+        return 'typescript';
     // ── Python ───────────────────────────────────────────────────────────────
     const hasPyProject = await exists(path.join(root, 'pyproject.toml'));
     const hasRequirements = await exists(path.join(root, 'requirements.txt'));
@@ -86,7 +94,12 @@ export async function detectProjectType(repoRoot) {
  * scan returns 'unknown' (e.g. repos that only contain instruction files, no source).
  * Checks the combined content of all scanned instruction files for strong signals.
  *
- * Detection order: nextjs → unity → typescript → dotnet → python → go → rust → unknown
+ * Detection order: nextjs → unity → dotnet → typescript → python → go → rust → unknown
+ *
+ * .NET is checked before typescript for the same reason as in the file-system
+ * probe above: .NET repos commonly mention JS tooling (pnpm, npm run, jest) in
+ * their instructions, so the broader typescript signals must not shadow the
+ * more specific .NET ones.
  */
 export function detectProjectTypeFromContent(files) {
     const combined = files.map((f) => f.content).join('\n');
@@ -96,12 +109,12 @@ export function detectProjectTypeFromContent(files) {
     if ((/\bunity\b/i.test(combined) && /\b(lts|editor|hub|engine)\b/i.test(combined)) || /\bmonobehaviour\b|\bunityengine\b|\bgameobject\b|\bprefab\b|\bscriptableobject\b/i.test(combined)) {
         return 'unity';
     }
-    if (/\btypescript\b|\btsconfig\b|\btsc\s|\bpnpm\b|\bnpm\s+run\b|\bvitest\b|\bjest\b/i.test(combined)) {
-        return 'typescript';
-    }
     if (/\bdotnet\b|\.sln\b|\.csproj\b|\bxunit\b|\bnunit\b|\bmstest\b/i.test(combined)) {
         return 'dotnet';
     }
+    if (/\btypescript\b|\btsconfig\b|\btsc\s|\bpnpm\b|\bnpm\s+run\b|\bvitest\b|\bjest\b/i.test(combined)) {
+        return 'typescript';
+    }
     if (/\bpython\b|\bpip\b|\bpoetry\b|\bvenv\b|\bpytest\b|\bpyproject\.toml\b/i.test(combined)) {
         return 'python';
     }

package/dist/project-type.js.map

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

package/dist/prompt-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-cache.d.ts","sourceRoot":"","sources":["../src/prompt-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqCjE,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAiIvF"}
+{"version":3,"file":"prompt-cache.d.ts","sourceRoot":"","sources":["../src/prompt-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqDjE,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAiIvF"}

package/dist/prompt-cache.js

@@ -1,5 +1,8 @@
+import { INSTRUCTION_FILE_TYPES } from './types.js';
+import { matchEvidence } from './evidence.js';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
+import { fileIdPath } from './finding-id.js';
 /**
  * B4: every id in this file was keyed by `${file.fileType}` — two files
  * sharing a fileType (e.g. CLAUDE.md and .claude/notes.md, both 'claude')
@@ -10,42 +13,48 @@ function promptCacheIssueId(kind, filePath) {
     return `prompt-cache-${kind}-${hash}`;
 }
 const DATE_PATTERNS = [
-    /\b(?:last\s+updated|last\s+modified|updated\s+at|modified\s+at|date)\b\s*:\s*\b\d{4}-\d{2}-\d{2}\b/i,
-    /\b\d{4}-\d{2}-\d{2}t\d{2}:\d{2}:\d{2}\b/i,
-    /\b(?:january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{1,2}(?:st|nd|rd|th)?,\s+\d{4}\b/i,
+    {
+        re: /\b(?:last\s+updated|last\s+modified|updated\s+at|modified\s+at|date)\b\s*:\s*\b\d{4}-\d{2}-\d{2}\b/i,
+        label: 'Dated "last updated"/"modified" line',
+    },
+    { re: /\b\d{4}-\d{2}-\d{2}t\d{2}:\d{2}:\d{2}\b/i, label: 'ISO 8601 timestamp' },
+    {
+        re: /\b(?:january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{1,2}(?:st|nd|rd|th)?,\s+\d{4}\b/i,
+        label: 'Long-form calendar date',
+    },
 ];
 const SCAN_REPORT_PATTERNS = [
-    /health\s+score\s*:\s*\d+/i,
-    /files\s+scanned\s*:\s*\d+/i,
-    /promptci\s+report/i,
-    /\bgenerated\s+by\s+promptci\b/i,
-    /latest\s+scan\s+results/i,
-    /scan\s+history/i,
+    { re: /health\s+score\s*:\s*\d+/i, label: 'Health-score line from a scan report' },
+    { re: /files\s+scanned\s*:\s*\d+/i, label: 'File-count line from a scan report' },
+    { re: /promptci\s+report/i, label: 'PromptCI report heading' },
+    { re: /\bgenerated\s+by\s+promptci\b/i, label: 'PromptCI generated-by marker' },
+    { re: /latest\s+scan\s+results/i, label: 'Pasted "latest scan results" section' },
+    { re: /scan\s+history/i, label: 'Pasted "scan history" section' },
 ];
 const BRANCH_TASK_PATTERNS = [
-    /current\s+branch\s*:\s*\S+/i,
-    /git\s+branch\s*:\s*\S+/i,
-    /current\s+task\s*:\s*\S+/i,
+    { re: /current\s+branch\s*:\s*\S+/i, label: 'Current-branch line' },
+    { re: /git\s+branch\s*:\s*\S+/i, label: 'Git-branch line' },
+    { re: /current\s+task\s*:\s*\S+/i, label: 'Current-task line' },
 ];
 const LOCAL_PATH_PATTERN = /(?:[a-zA-Z]:\\users\\[a-zA-Z0-9_-]+)|(?:\/users\/[a-zA-Z0-9_-]+\/)|(?:\/home\/(?!runner)[a-zA-Z0-9_-]+\/)/i;
 export function detectPromptCacheFriendliness(files) {
     const issues = [];
     // Focus only on persistent, always-loaded instruction files
-    const targetFiles = files.filter((f) => ['claude', 'agents', 'cursor', 'copilot', 'prompt'].includes(f.fileType));
+    const targetFiles = files.filter((f) => INSTRUCTION_FILE_TYPES.has(f.fileType));
     for (const file of targetFiles) {
         const fileName = path.basename(file.path);
         // 1. Timestamps and Dates
         for (const pat of DATE_PATTERNS) {
-            if (pat.test(file.content)) {
+            if (pat.re.test(file.content)) {
                 issues.push({
-                    id: promptCacheIssueId('volatile-timestamp', file.path),
+                    id: promptCacheIssueId('volatile-timestamp', fileIdPath(file)),
                     severity: 'warning',
                     category: 'context_bloat',
                     title: 'Volatile timestamp in instruction file',
                     summary: `The instruction file "${fileName}" contains a volatile date or timestamp. Frequently changing dates in persistent instruction files invalidate prompt caches.`,
                     filePaths: [file.path],
                     locations: [],
-                    evidence: [`Matched pattern: ${pat.toString()}`],
+                    evidence: [matchEvidence(file.content, pat.re, pat.label)],
                     recommendation: 'Move volatile dates to a separate task-specific prompt or scratch file, or remove them from canonical instructions.',
                     fixRecipe: 'Remove the "Last updated: <date>" or timestamp line from the file.',
                     confidence: 0.85,
@@ -55,16 +64,16 @@ export function detectPromptCacheFriendliness(files) {
         }
         // 2. Pasted Scan Outputs/Reports
         for (const pat of SCAN_REPORT_PATTERNS) {
-            if (pat.test(file.content)) {
+            if (pat.re.test(file.content)) {
                 issues.push({
-                    id: promptCacheIssueId('pasted-report', file.path),
+                    id: promptCacheIssueId('pasted-report', fileIdPath(file)),
                     severity: 'warning',
                     category: 'context_bloat',
                     title: 'Pasted scan report or summary in instructions',
                     summary: `The instruction file "${fileName}" contains pasted scan results or reports. Committing generated reports into canonical instruction files breaks prompt caching and bloats context.`,
                     filePaths: [file.path],
                     locations: [],
-                    evidence: [`Matched pattern: ${pat.toString()}`],
+                    evidence: [matchEvidence(file.content, pat.re, pat.label)],
                     recommendation: 'Link to the generated report file or read it on-demand instead of pasting its contents into canonical instructions.',
                     fixRecipe: 'Delete the pasted report summary block and reference the report file path instead.',
                     confidence: 0.9,
@@ -74,16 +83,16 @@ export function detectPromptCacheFriendliness(files) {
         }
         // 3. Current Branch or Task status
         for (const pat of BRANCH_TASK_PATTERNS) {
-            if (pat.test(file.content)) {
+            if (pat.re.test(file.content)) {
                 issues.push({
-                    id: promptCacheIssueId('volatile-branch-task', file.path),
+                    id: promptCacheIssueId('volatile-branch-task', fileIdPath(file)),
                     severity: 'warning',
                     category: 'context_bloat',
                     title: 'Volatile branch or task status in instructions',
                     summary: `The instruction file "${fileName}" contains active git branch or task details. Frequently updated task status or branch names break prompt caching.`,
                     filePaths: [file.path],
                     locations: [],
-                    evidence: [`Matched pattern: ${pat.toString()}`],
+                    evidence: [matchEvidence(file.content, pat.re, pat.label)],
                     recommendation: 'Move branch-specific notes and active task details to git commit messages, PR descriptions, or a temporary scratch file.',
                     fixRecipe: 'Remove active branch and task notes from the persistent instructions.',
                     confidence: 0.85,
@@ -95,7 +104,7 @@ export function detectPromptCacheFriendliness(files) {
         if (LOCAL_PATH_PATTERN.test(file.content)) {
             const match = file.content.match(LOCAL_PATH_PATTERN)?.[0] ?? '';
             issues.push({
-                id: promptCacheIssueId('local-paths', file.path),
+                id: promptCacheIssueId('local-paths', fileIdPath(file)),
                 severity: 'warning',
                 category: 'context_bloat',
                 title: 'Local machine paths in instructions',
@@ -132,7 +141,7 @@ export function detectPromptCacheFriendliness(files) {
         }
         if (maxTableRows > 15) {
             issues.push({
-                id: promptCacheIssueId('large-table', file.path),
+                id: promptCacheIssueId('large-table', fileIdPath(file)),
                 severity: 'warning',
                 category: 'context_bloat',
                 title: 'Large table in instruction file',