@promptci/core 0.2.1 → 0.3.0

package/dist/sarif.js

@@ -0,0 +1,357 @@
+/**
+ * SARIF 2.1.0 report generation for PromptCI scan results (pcic-aq2f).
+ *
+ * Competing tools already emit SARIF, which lands their findings in GitHub's
+ * Security tab for teams that gate merges on code scanning; PromptCI findings
+ * otherwise only show up in its own markdown/JSON report. This module maps a
+ * `ScanReport` onto a SARIF log without changing anything about how findings
+ * are detected or scored.
+ *
+ * Deterministic like the rest of the report pipeline (see report.ts /
+ * AGENTS.md): no timestamps, no run-invocation metadata, stable ordering.
+ */
+import * as nodePath from 'node:path';
+import { INSTRUCTION_FILE_TYPES } from './types.js';
+import { computeFingerprint } from './baseline.js';
+const PROMPTCI_REPO_URL = 'https://github.com/SeriousGeese/PromptCI';
+// No per-category anchor exists in the README today; point every rule at the
+// section that documents what gets detected until one does.
+const DETECTOR_REFERENCE_URL = `${PROMPTCI_REPO_URL}#what-gets-detected`;
+const SARIF_SCHEMA_URI = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/sarif-2.1/schema/sarif-schema-2.1.0.json';
+/**
+ * Severity → SARIF level mapping (pcic-aq2f judgment call).
+ *
+ * GitHub's code-scanning UI only recognizes three levels, and `error` is the
+ * only one that can block a PR by default. PromptCI's two "this is a real
+ * problem" tiers (`critical`, `high`) both map to `error` so either one is
+ * visible to a security-tab gate; `warning` keeps its name; `info` (the
+ * lowest, advisory tier) maps to SARIF's `note`, its "worth seeing, not a
+ * problem" level.
+ */
+const SEVERITY_TO_SARIF_LEVEL = {
+    critical: 'error',
+    high: 'error',
+    warning: 'warning',
+    info: 'note',
+};
+const CATEGORY_INFO = {
+    duplicate: {
+        name: 'Duplicate instruction content',
+        shortDescription: 'Repeated or near-identical guidance across sections or files.',
+        defaultLevel: 'warning',
+    },
+    conflict: {
+        name: 'Conflicting directives',
+        shortDescription: 'Contradictory instructions, versions, or competing framework/tech choices.',
+        defaultLevel: 'error',
+    },
+    context_bloat: {
+        name: 'Context bloat',
+        shortDescription: 'Instruction files exceeding size or token-budget thresholds.',
+        defaultLevel: 'warning',
+    },
+    missing_context: {
+        name: 'Missing setup context',
+        shortDescription: 'Missing setup, validation, or project-specific guidance.',
+        defaultLevel: 'warning',
+    },
+    stale_instruction: {
+        name: 'Stale instructions',
+        shortDescription: 'Old years, dated TODOs, deprecated wording, or outdated versions.',
+        defaultLevel: 'warning',
+    },
+    vague_guidance: {
+        name: 'Vague guidance',
+        shortDescription: 'Guidance too vague for an agent or contributor to act on.',
+        defaultLevel: 'note',
+    },
+    structure: {
+        name: 'Structural issue',
+        shortDescription: 'Malformed suppression annotations or other structural problems.',
+        defaultLevel: 'warning',
+    },
+    command_validity: {
+        name: 'Invalid command reference',
+        shortDescription: 'Documented commands, scripts, or make targets that no longer exist.',
+        defaultLevel: 'warning',
+    },
+    agent_practices: {
+        name: 'Agent practice gap',
+        shortDescription: 'Gaps in agent-facing operational guidance.',
+        defaultLevel: 'note',
+    },
+    ai_config: {
+        name: 'AI setup config rot',
+        shortDescription: 'Agent Skills, subagents, hooks/settings, MCP servers, or editor rule files drifted from filesystem reality.',
+        defaultLevel: 'warning',
+    },
+    security: {
+        name: 'Security or privacy gap',
+        shortDescription: 'Security or privacy gaps in instruction guidance.',
+        defaultLevel: 'error',
+    },
+    custom: {
+        name: 'Custom rule finding',
+        shortDescription: "A finding from the repository's own .promptci/custom-rules.json rules.",
+        defaultLevel: 'warning',
+    },
+};
+/**
+ * Suppressed findings are included rather than omitted (pcic-aq2f judgment
+ * call): dropping them would make a repo's suppressions invisible in the
+ * Security tab, where a reviewer might reasonably want to see what was
+ * silenced and why. SARIF's `suppressions` field marks a result as
+ * suppressed — GitHub's SARIF documentation does not promise any particular
+ * handling of a `suppressions`-bearing result, so this is "marked suppressed
+ * in the SARIF," not a guarantee about how a given consumer displays it. The
+ * justification is generic because the inline `promptci-ignore` reason text
+ * is not threaded onto `PromptCiIssue` today.
+ */
+const SUPPRESSED_JUSTIFICATION = "Suppressed via an inline `promptci-ignore` annotation in the scanned repository.";
+/**
+ * A `ScanReport.repoPath`/finding path is produced by whatever machine ran
+ * the scan — a Windows checkout (`C:\git\repo`) or a POSIX one
+ * (`/home/runner/work/repo`) — and this module must handle either SHAPE
+ * regardless of which platform IT is running on (a repo scanned on Windows
+ * can still have its SARIF generated, or tested, on Linux CI and vice versa).
+ * `node:path`'s plain `path.relative`/`path.isAbsolute` bind to the CURRENT
+ * process's platform, so on Linux they treat a Windows-shaped path like
+ * `C:\git\repo\sub\CLAUDE.md` as just an opaque string with no recognized
+ * separators — `path.relative` between two such strings does not compute a
+ * real relative path, and the "is this outside the repo" check in
+ * `toRelativeUri` below then misfires. Detect the SHAPE of the input paths
+ * instead and pick `path.win32` or `path.posix` explicitly, independent of
+ * `process.platform`.
+ */
+function isWindowsShapedPath(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p) || p.includes('\\');
+}
+/** Platform-independent basename (see isWindowsShapedPath) for a single path. */
+function basenameOf(p) {
+    return (isWindowsShapedPath(p) ? nodePath.win32 : nodePath.posix).basename(p);
+}
+/**
+ * Forward-slash, percent-encoded, repo-relative URI for a SARIF
+ * artifactLocation.uri — or null when `absPath` does not resolve inside
+ * `repoPath` at all (such a location is dropped rather than pointing outside
+ * the scanned tree). `relative()` can return a path that climbs out with a
+ * leading `..`, or (given an unrelated absolute path) something that is not
+ * relative at all; only those two cases mean "outside" — a real directory or
+ * file NAMED `..something` (e.g. `..hidden/x`) does not start with `..`
+ * followed by a separator (or equal `..` outright), so it is left alone.
+ */
+function toRelativeUri(absPath, repoPath) {
+    // Platform-independent (see isWindowsShapedPath): either input looking
+    // Windows-shaped is enough to pick path.win32 for BOTH, since relative()
+    // needs a consistent separator convention across the two arguments.
+    const pathImpl = isWindowsShapedPath(repoPath) || isWindowsShapedPath(absPath) ? nodePath.win32 : nodePath.posix;
+    const rel = pathImpl.relative(repoPath, absPath);
+    if (rel === '..' || rel.startsWith(`..${pathImpl.sep}`) || pathImpl.isAbsolute(rel)) {
+        return null;
+    }
+    const posix = rel.split(pathImpl.sep).join('/');
+    // RFC 3986: each path SEGMENT is percent-encoded independently, so a
+    // literal '/' produced by encoding one segment can never be mistaken for a
+    // path separator, and characters like '#', '%', ' ', or non-ASCII bytes in
+    // a real filename round-trip into a valid uri-reference.
+    return posix
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+}
+/** One SARIF location for `absPath`, or null if it falls outside the repo (see toRelativeUri). */
+function buildOneLocation(absPath, rel, startLine, endLine) {
+    const uri = rel(absPath);
+    if (uri === null)
+        return null;
+    // A detector-supplied line number is always >= 1 in practice, but never
+    // invent a line (or trust a stray 0/negative one) for a result that has
+    // none — SARIF regions are 1-based, and a fabricated "line 1" would point a
+    // reviewer at the wrong text for what is really a file-level finding.
+    const region = startLine !== undefined && startLine >= 1
+        ? { startLine, ...(endLine !== undefined && endLine >= startLine ? { endLine } : {}) }
+        : undefined;
+    return {
+        physicalLocation: {
+            artifactLocation: { uri, uriBaseId: '%SRCROOT%' },
+            ...(region ? { region } : {}),
+        },
+    };
+}
+/**
+ * SARIF locations for one finding, plus whether a fallback location had to
+ * be substituted (pcic-aq2f #3/#12): a finding with no usable location — no
+ * `locations` entries (or none that resolve inside the repo), and no
+ * `filePaths` either (or none that resolve inside the repo) — would
+ * otherwise serialize to `locations: []`, which GitHub's code-scanning
+ * ingestion silently drops. Falling back to the repo's primary instruction
+ * file (whichever of AGENTS.md/CLAUDE.md the scan found first, else the
+ * first scanned instruction file) keeps the finding visible, with no region
+ * attached since the fallback file is not where the finding specifically is.
+ * When nothing was scanned at all, there is nothing to fall back to and the
+ * result legitimately carries no locations.
+ */
+function buildLocations(issue, rel, fallbackAbsPath) {
+    const fromLocations = issue.locations
+        .map((loc) => buildOneLocation(loc.filePath, rel, loc.startLine, loc.endLine))
+        .filter((l) => l !== null);
+    if (fromLocations.length > 0)
+        return { locations: fromLocations, usedFallback: false };
+    const fromFilePaths = issue.filePaths
+        .map((fp) => buildOneLocation(fp, rel, undefined, undefined))
+        .filter((l) => l !== null);
+    if (fromFilePaths.length > 0)
+        return { locations: fromFilePaths, usedFallback: false };
+    if (fallbackAbsPath) {
+        const fallback = buildOneLocation(fallbackAbsPath, rel, undefined, undefined);
+        if (fallback)
+            return { locations: [fallback], usedFallback: true };
+    }
+    return { locations: [], usedFallback: false };
+}
+/**
+ * Title + recommendation, worded as cautiously as the issue itself already
+ * is. Falls back to the title when `summary` is somehow empty, so a result
+ * never serializes with blank message text. `fallbackNote`, when set,
+ * documents that `locations` points at the repo's primary instruction file
+ * rather than the finding's actual location (see buildLocations).
+ */
+function buildMessageText(issue, fallbackNote) {
+    const summary = issue.summary.trim() || issue.title.trim();
+    const recommendation = issue.recommendation.trim();
+    const base = recommendation ? `${summary} Recommendation: ${recommendation}` : summary;
+    return fallbackNote ? `${base} ${fallbackNote}` : base;
+}
+/**
+ * Sort key used to order results deterministically: primary file, then
+ * primary line, then category, then the issue's own id — independent of
+ * detector run order. Out-of-repo locations/filePaths are excluded the same
+ * way buildLocations excludes them, so the key never diverges from where a
+ * result's own locations actually point.
+ */
+function sortKey(issue, rel) {
+    const loc = issue.locations.find((l) => l.startLine !== undefined && rel(l.filePath) !== null) ??
+        issue.locations.find((l) => rel(l.filePath) !== null);
+    const file = loc ? rel(loc.filePath) : issue.filePaths.map(rel).find((p) => p !== null) ?? '';
+    const line = loc?.startLine ?? 0;
+    return [file, String(line).padStart(10, '0'), issue.category, issue.id].join('\u0000');
+}
+/**
+ * Ordinal (UTF-16 code-unit) string comparison, not `localeCompare`:
+ * `localeCompare`'s collation depends on the running engine's ICU data and
+ * the active locale, which is not guaranteed identical between the machine
+ * that runs this and CI's — the same input could sort differently and break
+ * the "identical reports produce byte-identical SARIF" guarantee. Plain
+ * `<`/`>` on strings compares UTF-16 code units and is the same everywhere
+ * Node runs.
+ */
+function ordinalCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * `promptci/v1` is PromptCI's OWN stable-identity key (the same
+ * category+title+filePaths+evidence fingerprint `--baseline` already uses),
+ * not GitHub's `primaryLocationLineHash` — GitHub computes and uses that one
+ * itself. The fingerprint deliberately excludes line numbers, so two distinct
+ * findings of the same category/title/evidence (e.g. the same duplicate
+ * check firing on two different line ranges) can share a raw value; the
+ * caller's trailing `:N` (rawFingerprintWithSuffix) keeps their
+ * partialFingerprints distinct WITHIN this run without touching what makes
+ * two findings "the same" ACROSS runs.
+ */
+function buildResult(issue, rel, rawFingerprintWithSuffix, ruleIndex, suppressed, fallbackAbsPath) {
+    const { locations, usedFallback } = buildLocations(issue, rel, fallbackAbsPath);
+    const fallbackNote = usedFallback && fallbackAbsPath
+        ? `(No specific location was recorded for this finding; pointing at ${basenameOf(fallbackAbsPath)} as the repository's primary instruction file.)`
+        : undefined;
+    const result = {
+        ruleId: issue.category,
+        ruleIndex,
+        level: SEVERITY_TO_SARIF_LEVEL[issue.severity],
+        message: { text: buildMessageText(issue, fallbackNote) },
+        locations,
+        partialFingerprints: { 'promptci/v1': rawFingerprintWithSuffix },
+    };
+    if (suppressed) {
+        result.suppressions = [{ kind: 'external', justification: SUPPRESSED_JUSTIFICATION }];
+    }
+    return result;
+}
+function buildRule(category) {
+    const info = CATEGORY_INFO[category];
+    return {
+        id: category,
+        name: info.name,
+        shortDescription: { text: info.shortDescription },
+        helpUri: DETECTOR_REFERENCE_URL,
+        defaultConfiguration: { level: info.defaultLevel },
+    };
+}
+/**
+ * Absolute path of the repo's "primary" instruction file, for buildLocations'
+ * fallback: whichever of AGENTS.md/CLAUDE.md was scanned first (scan order,
+ * not alphabetical), else the first scanned instruction-type file, else
+ * undefined when nothing was scanned at all.
+ */
+function primaryInstructionFile(report) {
+    const scanned = report.filesScanned.filter((f) => f.aliasOf === undefined && INSTRUCTION_FILE_TYPES.has(f.fileType));
+    const primary = scanned.find((f) => {
+        const base = basenameOf(f.path).toLowerCase();
+        return base === 'agents.md' || base === 'claude.md';
+    });
+    return (primary ?? scanned[0])?.path;
+}
+/**
+ * Serialize a ScanReport to a SARIF 2.1.0 log.
+ *
+ * `toolVersion` is threaded in by the caller (the CLI's own `--version`
+ * value) rather than read from a package.json here, so this module stays
+ * decoupled from any particular package's on-disk layout.
+ *
+ * Active issues and suppressed issues are both included (suppressed ones
+ * carry a `suppressions` entry — see SUPPRESSED_JUSTIFICATION above); ruleId
+ * is the issue's `category`, the only detector/category identifier that is
+ * both present on every issue and stable across detector refactors.
+ */
+export function generateSarifReport(report, toolVersion, pretty = true) {
+    const rel = (absPath) => toRelativeUri(absPath, report.repoPath);
+    const fallbackAbsPath = primaryInstructionFile(report);
+    const entries = [
+        ...report.issues.map((issue) => ({ issue, suppressed: false })),
+        ...(report.suppressedIssues ?? []).map((issue) => ({ issue, suppressed: true })),
+    ];
+    entries.sort((a, b) => ordinalCompare(sortKey(a.issue, rel), sortKey(b.issue, rel)));
+    const categoriesUsed = [...new Set(entries.map(({ issue }) => issue.category))].sort(ordinalCompare);
+    const rules = categoriesUsed.map((category) => buildRule(category));
+    const ruleIndexOf = new Map(categoriesUsed.map((category, i) => [category, i]));
+    // Raw (pre-suffix) fingerprints can collide within a single run — the
+    // fingerprint excludes line numbers — so track how many of each have been
+    // seen, in the already-established sort order, and give each occurrence a
+    // 0-based `:N` suffix (see buildResult).
+    const fingerprintOccurrence = new Map();
+    const results = entries.map(({ issue, suppressed }) => {
+        const rawFingerprint = computeFingerprint(issue, report.repoPath);
+        const suffix = fingerprintOccurrence.get(rawFingerprint) ?? 0;
+        fingerprintOccurrence.set(rawFingerprint, suffix + 1);
+        return buildResult(issue, rel, `${rawFingerprint}:${suffix}`, ruleIndexOf.get(issue.category), suppressed, fallbackAbsPath);
+    });
+    const log = {
+        $schema: SARIF_SCHEMA_URI,
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'PromptCI',
+                        version: toolVersion,
+                        informationUri: PROMPTCI_REPO_URL,
+                        rules,
+                    },
+                },
+                results,
+            },
+        ],
+    };
+    return pretty ? JSON.stringify(log, null, 2) : JSON.stringify(log);
+}
+//# sourceMappingURL=sarif.js.map

package/dist/sarif.js.map

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

package/dist/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAiB,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgCvE,wBAAsB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAwDhE"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,KAAK,EAAiB,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgCvE,wBAAsB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CA6DhE"}

package/dist/scan.js

@@ -8,6 +8,7 @@ import { runDetectors } from './detectors.js';
 import { parseSuppressions, buildValidationIssues, applySuppressions } from './suppression.js';
 import { computeHealthScore, selectTopFixes } from './health-score.js';
 import { filterNewIssues } from './baseline.js';
+import { annotateIssueTokens, computeAddressableTokens } from './token-estimates.js';
 import { SKILL_SUPPLY_CHAIN_TAG } from './skill-supply-chain.js';
 /**
  * Inline suppression, with one carve-out: a skill-supply-chain finding is never
@@ -44,7 +45,9 @@ export async function scan(input) {
     // Suppressed issues are excluded from health score and topFixes.
     const annotations = parseSuppressions(allScannedFiles);
     const allIssues = [...issues, ...buildValidationIssues(annotations)];
-    const { active, suppressed } = applyScanSuppressions(allIssues, annotations, context);
+    const { active: activeRaw, suppressed: suppressedRaw } = applyScanSuppressions(allIssues, annotations, context);
+    const active = annotateIssueTokens(activeRaw, allScannedFiles, context.aliasFiles);
+    const suppressed = annotateIssueTokens(suppressedRaw, allScannedFiles, context.aliasFiles);
     const healthScore = computeHealthScore(active);
     const topFixes = selectTopFixes(active);
     let newIssues;
@@ -60,7 +63,10 @@ export async function scan(input) {
         repoPath: context.repoRoot,
         projectType: context.projectType,
         healthScore,
-        metrics: context.metrics,
+        metrics: {
+            ...context.metrics,
+            estimatedAddressableTokens: computeAddressableTokens(active, context.files, context.aliasFiles),
+        },
         // Symlink aliases are inventory only (see RepoContext.aliasFiles): they are
         // not scanned, so they carry no annotations to parse above. Their content and
         // counts are zeroed so a consumer summing filesScanned does not count the

package/dist/scan.js.map

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

package/dist/scanner.d.ts

@@ -1,7 +1,8 @@
 import type { InstructionFile, InstructionSection, ScanInput } from './types.js';
+import { RepoTree } from './repo-tree.js';
 import type { GitSymlinkOracle } from './git-symlinks.js';
-export declare const MAX_FILE_SIZE: number;
-export declare const BINARY_CHECK_BYTES = 512;
+import { MAX_FILE_SIZE, BINARY_CHECK_BYTES } from './discovery.js';
+export { MAX_FILE_SIZE, BINARY_CHECK_BYTES };
 /**
  * Splits markdown into heading-delimited sections.
  *
@@ -58,6 +59,6 @@ export declare function foldTextSymlinks(files: InstructionFile[], aliases: Inst
  *    folded into an alias of that file, so both platforms scan the same repo alike
  *    (see {@link foldTextSymlinks}).
  */
-export declare function scanFilesWithAliases(input: ScanInput): Promise<ScanFilesResult>;
+export declare function scanFilesWithAliases(input: ScanInput, tree?: RepoTree): Promise<ScanFilesResult>;
 export declare function scanFiles(input: ScanInput): Promise<InstructionFile[]>;
 //# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AA8D1D,eAAO,MAAM,aAAa,QAAa,CAAC;AACxC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAiEtC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,kBAAkB,EAAE,CAuDtB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMhD;AAyBD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AA4HvF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAgChI;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAiGrF;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5E"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI3F,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAgD,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAoBjH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC;AAiE7C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,kBAAkB,EAAE,CAuDtB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMhD;AAkBD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AA4HvF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAgChI;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAC,CAuGtG;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5E"}

package/dist/scanner.js

@@ -5,66 +5,26 @@ import * as path from 'node:path';
 import { scanFencedLines } from './markdown-fences.js';
 import { isWithinRoot, realPath, realPathWithinRoot } from './path-containment.js';
 import { createGitSymlinkOracle } from './git-symlinks.js';
-const DEFAULT_PATTERNS = [
-    // Core AI instruction files
-    'CLAUDE.md',
-    'AGENTS.md',
-    '.cursorrules',
-    '.windsurfrules',
-    // Gemini CLI. Root only, like CLAUDE.md/AGENTS.md above.
-    'GEMINI.md',
-    // Cline: a single `.clinerules` file OR a `.clinerules/` directory of
-    // markdown rule files (fast-glob's onlyFiles default means the bare pattern
-    // matches only the file form; defaultPatterns() drops the directory globs
-    // when `.clinerules` is a file). `.clinerules/workflows/` holds on-demand
-    // slash-command workflows, not always-loaded rules, so it is left out.
-    '.clinerules',
-    '.clinerules/**/*.md',
-    '!.clinerules/workflows/**',
-    // Agent persona files (SOUL.md, USER.md, TOOLS.md). Repo ROOT only: the
-    // names are generic enough that a nested `docs/USER.md` is far more likely a
-    // user guide than an agent persona. deriveFileType enforces the same rule
-    // when an explicit `include` pattern pulls a nested copy in.
-    'SOUL.md',
-    'USER.md',
-    'TOOLS.md',
-    // Cursor IDE rules
-    '.cursor/rules/**',
-    // GitHub Copilot instructions (legacy + new per-file format)
-    '.github/copilot-instructions.md',
-    '.github/instructions/**/*.md',
-    // Claude memory / settings directory
-    '.claude/**/*.md',
-    // README is often the only context file in small repos
-    'README.md',
-    // BUG-I1: Additional root-level instruction files that agents commonly read.
-    // Explicit names only — keeps the set narrow enough to avoid scanning docs/
-    // but broad enough to catch QA.md, CONTRIBUTING.md, and similar convention files.
-    'QA.md',
-    'CONTRIBUTING.md',
-    'ARCHITECTURE.md',
-    'DEVELOPMENT.md',
-    'CODING_STANDARDS.md',
-    'CONVENTIONS.md',
-    'GUIDELINES.md',
-    // Explicit AI/prompt directories only — not generic docs/
-    'ai/**/*.md',
-    'ai-instructions/**/*.md',
-    'prompts/**/*.md',
-    'system-prompts/**/*.md',
-];
-// NOTE: docs/**/*.md is intentionally excluded — docs directories typically
-// contain project documentation (QA reports, plans, guides) that are not AI
-// instruction files and cause false positive context-bloat and conflict findings.
+import { RepoTree } from './repo-tree.js';
+import { SCAN_IGNORE_DIRS, defaultInstructionPatterns, MAX_FILE_SIZE, BINARY_CHECK_BYTES } from './discovery.js';
 // 'worktrees'/'.worktrees' covers git worktree checkouts nested anywhere in the
 // tree (e.g. Claude Code's .claude/worktrees/<name>/, or a top-level worktrees/
 // dir used by other agent tooling) — these are full copies of the repo and
 // would otherwise be scanned as duplicate instruction-file trees.
-const IGNORE_DIRS = ['.git', 'node_modules', 'Library', 'Temp', 'bin', 'obj', 'dist', 'build', 'worktrees', '.worktrees'];
-// Exported so ai_config discovery (ai-config.ts) applies the exact same
-// size/binary policy as this scanner — one definition of "scannable file".
-export const MAX_FILE_SIZE = 500 * 1024;
-export const BINARY_CHECK_BYTES = 512;
+//
+// NOTE: docs/**/*.md is intentionally excluded from the default patterns —
+// docs directories typically contain project documentation (QA reports,
+// plans, guides) that are not AI instruction files and cause false positive
+// context-bloat and conflict findings. The patterns themselves live in
+// discovery.ts (`DEFAULT_INSTRUCTION_PATTERNS`), the one place scanner.ts and
+// a filesystem-free consumer (`selectScanPaths`) both read them from.
+const IGNORE_DIRS = SCAN_IGNORE_DIRS;
+// Re-exported so ai_config discovery (ai-config.ts) and the many other
+// importers of `MAX_FILE_SIZE`/`BINARY_CHECK_BYTES` from this module keep
+// their import path; the values themselves live in discovery.ts, the one
+// place scanner.ts and the filesystem-free `selectScanPaths` both read them
+// from — one definition of "scannable file".
+export { MAX_FILE_SIZE, BINARY_CHECK_BYTES };
 const PERSONA_ROOT_PATHS = new Set(['/SOUL.md', '/USER.md', '/TOOLS.md']);
 // Takes the repo-root-relative path (not the absolute path): classification must
 // depend only on where a file sits INSIDE the scanned repo. Using the absolute
@@ -200,27 +160,20 @@ export function isBinary(buffer) {
     }
     return false;
 }
-const CLINE_DIR_PATTERNS = new Set([
-    '.clinerules/**/*.md',
-    '!.clinerules/workflows/**',
-]);
 /**
- * DEFAULT_PATTERNS, minus the `.clinerules/` directory globs unless
- * `.clinerules` really is a directory. fast-glob scandirs `.clinerules` to
- * expand them, and a FILE of that name (Cline's single-file form) makes it
- * throw ENOTDIR — which scanFiles' catch turned into an empty scan of the
- * WHOLE repo. `suppressErrors` now contains that too; dropping the globs
- * keeps the default scan from relying on it.
+ * discovery.ts's `DEFAULT_INSTRUCTION_PATTERNS`, minus the `.clinerules/`
+ * directory globs unless `.clinerules` really is a directory. fast-glob
+ * scandirs `.clinerules` to expand them, and a FILE of that name (Cline's
+ * single-file form) makes it throw ENOTDIR — which scanFiles' catch turned
+ * into an empty scan of the WHOLE repo. `suppressErrors` now contains that
+ * too; dropping the globs keeps the default scan from relying on it.
  */
-async function defaultPatterns(repoRoot) {
-    let clineIsDir = false;
-    try {
-        clineIsDir = (await fs.stat(path.join(repoRoot, '.clinerules'))).isDirectory();
-    }
-    catch {
-        // absent — the directory globs would match nothing anyway
-    }
-    return clineIsDir ? DEFAULT_PATTERNS : DEFAULT_PATTERNS.filter((p) => !CLINE_DIR_PATTERNS.has(p));
+function defaultPatterns(tree) {
+    // pcic-e6xa: `.clinerules` is a fixed name, but whether it is a FILE or a
+    // DIRECTORY changes what the scan reads — so it is asked through the tree,
+    // which never follows a link out of the root and lets a caller's inventory
+    // answer when the repository is not on disk (pcic-csf).
+    return [...defaultInstructionPatterns(tree.isDir('.clinerules'))];
 }
 /** The canonical real path, or null when it does not exist. Kept apart from `realPath` (used only to group names). */
 function resolveReal(p) {
@@ -408,12 +361,18 @@ export function foldTextSymlinks(files, aliases, oracle) {
  *    folded into an alias of that file, so both platforms scan the same repo alike
  *    (see {@link foldTextSymlinks}).
  */
-export async function scanFilesWithAliases(input) {
+export async function scanFilesWithAliases(input, tree) {
     const repoRoot = path.resolve(input.repoPath);
     const realRoot = resolveReal(repoRoot) ?? repoRoot;
+    // The scan's tree when the caller has one (buildRepoContext); otherwise a
+    // plain one over this root, carrying any inventory the input named.
+    const repoTree = tree ?? new RepoTree(repoRoot, {
+        ...(input.knownPaths !== undefined ? { knownPaths: input.knownPaths } : {}),
+        ...(input.knownPathsComplete !== undefined ? { knownPathsComplete: input.knownPathsComplete } : {}),
+    });
     const patterns = (input.include && input.include.length > 0)
         ? input.include
-        : await defaultPatterns(repoRoot);
+        : defaultPatterns(repoTree);
     const ignorePatterns = [
         ...IGNORE_DIRS.map((d) => `**/${d}/**`),
         ...(input.exclude ?? []),