@kogu/context-check 0.1.0

package/dist/analyzer/rules/large-file.js

@@ -0,0 +1,41 @@
+/**
+ * Large instruction detection (Spec §20).
+ *
+ * A file being large is not inherently bad, but a file above the token
+ * threshold may contribute significantly to model context. In the MVP both
+ * the notice and warning thresholds map to `label=CONTEXT`, `severity=info`
+ * through the normative mapping; we only ever emit `large-file` findings.
+ *
+ * Note: the `warningFileTokens` threshold is reserved (Spec §11) and produces
+ * no additional severity in the MVP — the taxonomy keeps `info` here.
+ */
+import { DEFAULT_ANALYSIS_OPTIONS } from "../types.js";
+import { makeFinding } from "./mapping.js";
+export const largeFileRule = {
+    name: "large-file",
+    run(artifacts, context) {
+        const threshold = context.options.largeFileTokens ??
+            DEFAULT_ANALYSIS_OPTIONS.largeFileTokens;
+        const findings = [];
+        for (const artifact of artifacts) {
+            const tokens = artifact.metadata.estimatedTokens;
+            if (tokens <= threshold)
+                continue;
+            findings.push(makeFinding({
+                type: "large-file",
+                filePaths: [artifact.path],
+                title: "Instruction file is unusually large",
+                description: `${artifact.path} is estimated at ~${formatTokens(tokens)} tokens. ` +
+                    `This file is relatively large and may contribute significantly to model context.`,
+                recommendation: `Consider whether all sections are still needed, or split unrelated ` +
+                    `instructions into smaller scoped files.`,
+            }));
+        }
+        return findings;
+    },
+};
+/** Formats a token count with thousands separators, e.g. 4800 -> "4,800". */
+export function formatTokens(tokens) {
+    return tokens.toLocaleString("en-US");
+}
+//# sourceMappingURL=large-file.js.map

package/dist/analyzer/rules/large-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"large-file.js","sourceRoot":"","sources":["../../../src/analyzer/rules/large-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,wBAAwB,EAAqB,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,YAAY;IAClB,GAAG,CAAC,SAAS,EAAE,OAAO;QACpB,MAAM,SAAS,GACb,OAAO,CAAC,OAAO,CAAC,eAAe;YAC/B,wBAAwB,CAAC,eAAe,CAAC;QAC3C,MAAM,QAAQ,GAAG,EAAE,CAAC;QAEpB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC;YACjD,IAAI,MAAM,IAAI,SAAS;gBAAE,SAAS;YAElC,QAAQ,CAAC,IAAI,CACX,WAAW,CAAC;gBACV,IAAI,EAAE,YAAY;gBAClB,SAAS,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAC1B,KAAK,EAAE,qCAAqC;gBAC5C,WAAW,EACT,GAAG,QAAQ,CAAC,IAAI,qBAAqB,YAAY,CAAC,MAAM,CAAC,WAAW;oBACpE,kFAAkF;gBACpF,cAAc,EACZ,qEAAqE;oBACrE,yCAAyC;aAC5C,CAAC,CACH,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/dist/analyzer/rules/mapping.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Finding factory + normative type/label/severity/confidence mapping
+ * (Spec §10, §13, Rule 17, Rule 27).
+ *
+ * Analyzers must never invent their own `label`, `severity` or `confidence`
+ * values. This mapping is the single source of truth; a rule only supplies a
+ * `type` and the factory resolves the public fields.
+ */
+import type { Finding, FindingConfidence, FindingLabel, FindingSeverity, FindingType } from "../../types/finding.js";
+export interface FindingSpec {
+    type: FindingType;
+    filePaths: string[];
+    title: string;
+    description: string;
+    recommendation?: string;
+}
+interface NormativeMeta {
+    label: FindingLabel;
+    severity: FindingSeverity;
+    confidence: FindingConfidence;
+}
+/** Normative mapping (Spec §10 table). */
+export declare const NORMATIVE_MAPPING: Record<FindingType, NormativeMeta>;
+/**
+ * Produces a fully-populated Finding with a deterministic id and the
+ * normative label/severity/confidence resolved from `type`.
+ */
+export declare function makeFinding(spec: FindingSpec): Finding;
+export {};

package/dist/analyzer/rules/mapping.js

@@ -0,0 +1,51 @@
+/**
+ * Finding factory + normative type/label/severity/confidence mapping
+ * (Spec §10, §13, Rule 17, Rule 27).
+ *
+ * Analyzers must never invent their own `label`, `severity` or `confidence`
+ * values. This mapping is the single source of truth; a rule only supplies a
+ * `type` and the factory resolves the public fields.
+ */
+import { createHash } from "node:crypto";
+/** Normative mapping (Spec §10 table). */
+export const NORMATIVE_MAPPING = {
+    duplicate: { label: "INFO", severity: "info", confidence: "high" },
+    repetition: { label: "INFO", severity: "info", confidence: "medium" },
+    "large-file": { label: "CONTEXT", severity: "info", confidence: "high" },
+    "scoped-no-match": {
+        label: "REVIEW",
+        severity: "notice",
+        confidence: "medium",
+    },
+    "high-stakes": { label: "CAUTION", severity: "notice", confidence: "medium" },
+    "context-overhead": {
+        label: "CONTEXT",
+        severity: "info",
+        confidence: "medium",
+    },
+};
+/**
+ * Produces a fully-populated Finding with a deterministic id and the
+ * normative label/severity/confidence resolved from `type`.
+ */
+export function makeFinding(spec) {
+    const meta = NORMATIVE_MAPPING[spec.type];
+    const id = findingId(spec.type, spec.filePaths, spec.title);
+    return {
+        id,
+        type: spec.type,
+        label: meta.label,
+        severity: meta.severity,
+        confidence: meta.confidence,
+        filePaths: [...spec.filePaths],
+        title: spec.title,
+        description: spec.description,
+        recommendation: spec.recommendation,
+    };
+}
+/** Deterministic id from type + paths + title. */
+function findingId(type, filePaths, title) {
+    const key = `${type}::${[...filePaths].sort().join(",")}::${title}`;
+    return `finding_${createHash("sha1").update(key).digest("hex").slice(0, 8)}`;
+}
+//# sourceMappingURL=mapping.js.map

package/dist/analyzer/rules/mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../../../src/analyzer/rules/mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAwBzC,0CAA0C;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAAuC;IACnE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;IAClE,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE;IACrE,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;IACxE,iBAAiB,EAAE;QACjB,KAAK,EAAE,QAAQ;QACf,QAAQ,EAAE,QAAQ;QAClB,UAAU,EAAE,QAAQ;KACrB;IACD,aAAa,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE;IAC7E,kBAAkB,EAAE;QAClB,KAAK,EAAE,SAAS;QAChB,QAAQ,EAAE,MAAM;QAChB,UAAU,EAAE,QAAQ;KACrB;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO;QACL,EAAE;QACF,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,SAAS,SAAS,CAChB,IAAiB,EACjB,SAAmB,EACnB,KAAa;IAEb,MAAM,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;IACpE,OAAO,WAAW,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AAC/E,CAAC"}

package/dist/analyzer/rules/repetition.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Repetition detection (Spec §18, Rule 21).
+ *
+ * Two strategies:
+ * - Markdown files: compare `heading + normalized section content`.
+ * - Files without headings: plain-text block fallback (paragraph/block
+ *   chunking), ignoring very short blocks.
+ *
+ * Only exact normalized text blocks are repetition candidates. The MVP does
+ * NOT use semantic similarity (Rule 13): semantically similar but textually
+ * different instructions are not flagged.
+ */
+import type { ConfigurationArtifact } from "../../types/configuration.js";
+import type { AnalyzerRule } from "../types.js";
+export declare const repetitionRule: AnalyzerRule;
+/** Extracts comparison units (markdown sections or plain-text blocks). */
+export declare function buildUnits(artifact: ConfigurationArtifact): Array<{
+    key: string;
+    display: string;
+}>;

package/dist/analyzer/rules/repetition.js

@@ -0,0 +1,80 @@
+/**
+ * Repetition detection (Spec §18, Rule 21).
+ *
+ * Two strategies:
+ * - Markdown files: compare `heading + normalized section content`.
+ * - Files without headings: plain-text block fallback (paragraph/block
+ *   chunking), ignoring very short blocks.
+ *
+ * Only exact normalized text blocks are repetition candidates. The MVP does
+ * NOT use semantic similarity (Rule 13): semantically similar but textually
+ * different instructions are not flagged.
+ */
+import { extractMarkdownSections, } from "../../parser/markdown.js";
+import { normalizeForComparison } from "../../parser/normalize.js";
+import { chunkPlainText } from "../../parser/plain-text.js";
+import { stripFrontmatter } from "../../parser/normalize.js";
+import { makeFinding } from "./mapping.js";
+export const repetitionRule = {
+    name: "repetition",
+    run(artifacts) {
+        const units = [];
+        for (const artifact of artifacts) {
+            for (const unit of buildUnits(artifact)) {
+                units.push({
+                    artifactPath: artifact.path,
+                    key: unit.key,
+                    display: unit.display,
+                });
+            }
+        }
+        // Group by normalized key; a key appearing more than once is a repetition.
+        const byKey = new Map();
+        for (const unit of units) {
+            const list = byKey.get(unit.key) ?? [];
+            list.push(unit);
+            byKey.set(unit.key, list);
+        }
+        const findings = [];
+        for (const matches of byKey.values()) {
+            if (matches.length < 2)
+                continue;
+            const paths = [...new Set(matches.map((m) => m.artifactPath))];
+            const detail = matches
+                .map((m) => `${m.artifactPath} (${m.display})`)
+                .slice(0, 3)
+                .join("; ");
+            findings.push(makeFinding({
+                type: "repetition",
+                filePaths: paths,
+                title: "Repeated instruction section",
+                description: `A normalized section appears ${matches.length} times across ` +
+                    `${paths.length} file(s): ${detail}.`,
+                recommendation: `Review whether the repeated guidance can be consolidated into a ` +
+                    `single source. Textually identical, not semantically similar.`,
+            }));
+        }
+        return findings;
+    },
+};
+/** Extracts comparison units (markdown sections or plain-text blocks). */
+export function buildUnits(artifact) {
+    const body = stripFrontmatter(artifact.content);
+    const sections = extractMarkdownSections(body);
+    if (sections.length > 0) {
+        return sections.map((section) => sectionUnit(section));
+    }
+    return chunkPlainText(body).map((block) => blockUnit(block));
+}
+function sectionUnit(section) {
+    // heading + normalized content (Spec §18).
+    const key = normalizeForComparison(`${section.heading}${section.content}`);
+    return { key, display: `# ${section.heading}` };
+}
+function blockUnit(block) {
+    const preview = block.normalized.length > 24
+        ? `${block.normalized.slice(0, 24)}...`
+        : block.normalized;
+    return { key: block.normalized, display: `"${preview}"` };
+}
+//# sourceMappingURL=repetition.js.map

package/dist/analyzer/rules/repetition.js.map

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

package/dist/analyzer/rules/scoped-no-match.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Scoped no-match finding (Spec §23, §25, Rule 18).
+ *
+ * Only runs when Git history is sufficient. For each artifact with `globs`
+ * (scope patterns), if NONE of its patterns matched any file change in the
+ * window, produce a `scoped-no-match` review finding.
+ *
+ * This is a REVIEW CANDIDATE, never an "unused"/"obsolete" label (Rule 8,
+ * Rule 9). Git activity alone is not evidence a rule is dead.
+ */
+import type { ConfigurationArtifact } from "../../types/configuration.js";
+import type { AnalyzerRule } from "../types.js";
+export declare const scopedNoMatchRule: AnalyzerRule;
+/** Whether an artifact has glob-scoped patterns that scoped analysis applies to. */
+export declare function hasScopedPatterns(artifact: ConfigurationArtifact): boolean;

package/dist/analyzer/rules/scoped-no-match.js

@@ -0,0 +1,46 @@
+/**
+ * Scoped no-match finding (Spec §23, §25, Rule 18).
+ *
+ * Only runs when Git history is sufficient. For each artifact with `globs`
+ * (scope patterns), if NONE of its patterns matched any file change in the
+ * window, produce a `scoped-no-match` review finding.
+ *
+ * This is a REVIEW CANDIDATE, never an "unused"/"obsolete" label (Rule 8,
+ * Rule 9). Git activity alone is not evidence a rule is dead.
+ */
+import { matchesChangedFile } from "../../git/history.js";
+import { makeFinding } from "./mapping.js";
+export const scopedNoMatchRule = {
+    name: "scoped-no-match",
+    run(artifacts, context) {
+        // Rule 18: skip entirely when Git history is insufficient.
+        if (!context.gitHistorySufficient) {
+            return [];
+        }
+        const changed = context.changedFilePaths ?? [];
+        const findings = [];
+        for (const artifact of artifacts) {
+            const patterns = artifact.scope?.patterns;
+            if (!patterns || patterns.length === 0)
+                continue;
+            const anyMatched = patterns.some((pattern) => matchesChangedFile(pattern, changed));
+            if (anyMatched)
+                continue;
+            findings.push(makeFinding({
+                type: "scoped-no-match",
+                filePaths: [artifact.path],
+                title: "No matching file changes for scoped rule",
+                description: `No file changes matched the scoped patterns for ${artifact.path} ` +
+                    `in the analyzed Git history window.`,
+                recommendation: `This does NOT mean the rule is unused. Consider reviewing its ` +
+                    `scope and purpose.`,
+            }));
+        }
+        return findings;
+    },
+};
+/** Whether an artifact has glob-scoped patterns that scoped analysis applies to. */
+export function hasScopedPatterns(artifact) {
+    return Boolean(artifact.scope?.patterns?.length);
+}
+//# sourceMappingURL=scoped-no-match.js.map

package/dist/analyzer/rules/scoped-no-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-no-match.js","sourceRoot":"","sources":["../../../src/analyzer/rules/scoped-no-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,CAAC,MAAM,iBAAiB,GAAiB;IAC7C,IAAI,EAAE,iBAAiB;IACvB,GAAG,CAAC,SAAS,EAAE,OAAO;QACpB,2DAA2D;QAC3D,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAClC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAC;QAC/C,MAAM,QAAQ,GAAG,EAAE,CAAC;QAEpB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;YAC1C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAEjD,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAC3C,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CACrC,CAAC;YACF,IAAI,UAAU;gBAAE,SAAS;YAEzB,QAAQ,CAAC,IAAI,CACX,WAAW,CAAC;gBACV,IAAI,EAAE,iBAAiB;gBACvB,SAAS,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAC1B,KAAK,EAAE,0CAA0C;gBACjD,WAAW,EACT,mDAAmD,QAAQ,CAAC,IAAI,GAAG;oBACnE,qCAAqC;gBACvC,cAAc,EACZ,gEAAgE;oBAChE,oBAAoB;aACvB,CAAC,CACH,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,QAA+B;IAC/D,OAAO,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC"}

package/dist/analyzer/run.d.ts

@@ -0,0 +1,25 @@
+/**
+ * End-to-end analyze runner (Spec §51).
+ *
+ * Wires the full local-first pipeline:
+ *   discover -> assess git history -> run analyzer rules -> report
+ *
+ * No content ever leaves the machine (Spec §36). Git access is only for
+ * metadata/sufficiency; it is skipped safely on any error (Spec §34).
+ */
+import { type GitSufficiencyResult } from "../git/sufficiency.js";
+import type { AnalysisReport } from "../types/report.js";
+import { type AnalysisOptions } from "./types.js";
+export interface RunAnalyzeOptions {
+    rootPath: string;
+    options?: Partial<AnalysisOptions>;
+}
+export interface RunAnalyzeResult {
+    report: AnalysisReport;
+    git: GitSufficiencyResult;
+}
+/**
+ * Runs discovery + analysis for a repo root. Never throws on missing git;
+ * when history is insufficient, scoped-rule findings are skipped (Rule 18).
+ */
+export declare function runAnalyze(opts: RunAnalyzeOptions): Promise<RunAnalyzeResult>;

package/dist/analyzer/run.js

@@ -0,0 +1,59 @@
+/**
+ * End-to-end analyze runner (Spec §51).
+ *
+ * Wires the full local-first pipeline:
+ *   discover -> assess git history -> run analyzer rules -> report
+ *
+ * No content ever leaves the machine (Spec §36). Git access is only for
+ * metadata/sufficiency; it is skipped safely on any error (Spec §34).
+ */
+import { discover } from "../discovery/discover.js";
+import { assessGitHistory, } from "../git/sufficiency.js";
+import { changedFilesInWindow } from "../git/history.js";
+import { analyze } from "./engine.js";
+import { DEFAULT_ANALYSIS_OPTIONS } from "./types.js";
+/**
+ * Runs discovery + analysis for a repo root. Never throws on missing git;
+ * when history is insufficient, scoped-rule findings are skipped (Rule 18).
+ */
+export async function runAnalyze(opts) {
+    const { rootPath } = opts;
+    const options = {
+        ...DEFAULT_ANALYSIS_OPTIONS,
+        ...opts.options,
+    };
+    const { artifacts } = await discover(rootPath);
+    let git;
+    let changedFilePaths;
+    try {
+        git = await assessGitHistory(rootPath, options.gitWindowDays);
+        if (git.sufficient && git.isGitRepo) {
+            changedFilePaths = await changedFilesInWindow(rootPath, options.gitWindowDays);
+        }
+        else {
+            changedFilePaths = [];
+        }
+    }
+    catch {
+        // Never fail the whole analysis because git is unavailable (Spec §34).
+        git = {
+            isGitRepo: false,
+            isShallow: false,
+            windowCommitCount: 0,
+            totalCommitCount: 0,
+            sufficient: false,
+        };
+        changedFilePaths = [];
+    }
+    const report = await analyze({
+        artifacts,
+        context: {
+            rootPath,
+            options,
+            changedFilePaths,
+            gitHistorySufficient: git.sufficient,
+        },
+    });
+    return { report, git };
+}
+//# sourceMappingURL=run.js.map

package/dist/analyzer/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/analyzer/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EACL,gBAAgB,GAEjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAwB,MAAM,YAAY,CAAC;AAY5E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAuB;IAEvB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC1B,MAAM,OAAO,GAAoB;QAC/B,GAAG,wBAAwB;QAC3B,GAAG,IAAI,CAAC,OAAO;KAChB,CAAC;IAEF,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE/C,IAAI,GAAyB,CAAC;IAC9B,IAAI,gBAAsC,CAAC;IAE3C,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;QAC9D,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YACpC,gBAAgB,GAAG,MAAM,oBAAoB,CAC3C,QAAQ,EACR,OAAO,CAAC,aAAa,CACtB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,gBAAgB,GAAG,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,GAAG,GAAG;YACJ,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,KAAK;YAChB,iBAAiB,EAAE,CAAC;YACpB,gBAAgB,EAAE,CAAC;YACnB,UAAU,EAAE,KAAK;SAClB,CAAC;QACF,gBAAgB,GAAG,EAAE,CAAC;IACxB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;QAC3B,SAAS;QACT,OAAO,EAAE;YACP,QAAQ;YACR,OAAO;YACP,gBAAgB;YAChB,oBAAoB,EAAE,GAAG,CAAC,UAAU;SACrC;KACF,CAAC,CAAC;IAEH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACzB,CAAC"}

package/dist/analyzer/severity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Severity threshold / exit-code semantics for CI (Spec §11, §34; product
+ * decision 2026).
+ *
+ * `--fail-on` consumes a severity level; a finding at or above the threshold
+ * causes a non-zero exit. Default (no `--fail-on`) is informational: findings
+ * never fail CI on their own.
+ *
+ * Ranking: info (0) < notice (1) < warning (2).
+ *
+ * Label→severity mapping (normative, Spec §10):
+ *   INFO → info, CONTEXT → info, REVIEW → notice, CAUTION → notice.
+ */
+import type { Finding, FindingSeverity } from "../types/finding.js";
+/** Accepted `--fail-on` values (severity level). */
+export type FailThreshold = FindingSeverity;
+/** Whether any finding meets or exceeds the threshold. */
+export declare function shouldFailOnSeverity(findings: Finding[], threshold: FailThreshold): boolean;
+/** Highest severity present in a set of findings, or "info" when empty. */
+export declare function maxSeverity(findings: Finding[]): FindingSeverity;
+export declare function isValidFailThreshold(value: string): value is FailThreshold;

package/dist/analyzer/severity.js

@@ -0,0 +1,39 @@
+/**
+ * Severity threshold / exit-code semantics for CI (Spec §11, §34; product
+ * decision 2026).
+ *
+ * `--fail-on` consumes a severity level; a finding at or above the threshold
+ * causes a non-zero exit. Default (no `--fail-on`) is informational: findings
+ * never fail CI on their own.
+ *
+ * Ranking: info (0) < notice (1) < warning (2).
+ *
+ * Label→severity mapping (normative, Spec §10):
+ *   INFO → info, CONTEXT → info, REVIEW → notice, CAUTION → notice.
+ */
+const SEVERITY_RANK = {
+    info: 0,
+    notice: 1,
+    warning: 2,
+};
+/** Whether any finding meets or exceeds the threshold. */
+export function shouldFailOnSeverity(findings, threshold) {
+    const min = SEVERITY_RANK[threshold];
+    return findings.some((f) => SEVERITY_RANK[f.severity] >= min);
+}
+/** Highest severity present in a set of findings, or "info" when empty. */
+export function maxSeverity(findings) {
+    let rank = 0;
+    let sev = "info";
+    for (const f of findings) {
+        if (SEVERITY_RANK[f.severity] > rank) {
+            rank = SEVERITY_RANK[f.severity];
+            sev = f.severity;
+        }
+    }
+    return sev;
+}
+export function isValidFailThreshold(value) {
+    return value === "info" || value === "notice" || value === "warning";
+}
+//# sourceMappingURL=severity.js.map

package/dist/analyzer/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.js","sourceRoot":"","sources":["../../src/analyzer/severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,aAAa,GAAoC;IACrD,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;CACX,CAAC;AAEF,0DAA0D;AAC1D,MAAM,UAAU,oBAAoB,CAClC,QAAmB,EACnB,SAAwB;IAExB,MAAM,GAAG,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;AAChE,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,QAAmB;IAC7C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,GAAG,GAAoB,MAAM,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC;YACrC,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACjC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,SAAS,CAAC;AACvE,CAAC"}

package/dist/analyzer/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Analyzer contract (Spec §15, §51).
+ *
+ * Each rule runs independently over the discovered artifacts and returns its
+ * own findings. Rules are kept free of presentation concerns (Rule 15) and
+ * platform-specific logic lives in adapters (Rule 14).
+ */
+import type { ConfigurationArtifact } from "../types/configuration.js";
+import type { Finding } from "../types/finding.js";
+/** Analysis-wide options, sourced from `.contextcheck.json` (Spec §52). */
+export interface AnalysisOptions {
+    /** Files larger than this (estimated tokens) become large-file findings. */
+    largeFileTokens: number;
+    /** Reserved for future `warning` severity (Spec §20). Not used in MVP. */
+    warningFileTokens: number;
+    /** Git history window (days) used by scoped-rule analysis (Spec §24, §52). */
+    gitWindowDays: number;
+}
+export declare const DEFAULT_ANALYSIS_OPTIONS: AnalysisOptions;
+/** Context handed to every rule (git state, options, repo root). */
+export interface AnalysisContext {
+    rootPath: string;
+    options: AnalysisOptions;
+    /** Paths changed in the Git window, when available. */
+    changedFilePaths?: string[];
+    /** Whether Git history is sufficient for scoped-rule analysis (Spec §24). */
+    gitHistorySufficient?: boolean;
+}
+/** A rule producing zero or more findings from the same artifact set. */
+export interface AnalyzerRule {
+    name: string;
+    run(artifacts: ConfigurationArtifact[], context: AnalysisContext): Promise<Finding[]> | Finding[];
+}
+/** A convenience no-op rule used to keep the pipeline stable while built. */
+export declare function emptyFindings(): Finding[];

package/dist/analyzer/types.js

@@ -0,0 +1,17 @@
+/**
+ * Analyzer contract (Spec §15, §51).
+ *
+ * Each rule runs independently over the discovered artifacts and returns its
+ * own findings. Rules are kept free of presentation concerns (Rule 15) and
+ * platform-specific logic lives in adapters (Rule 14).
+ */
+export const DEFAULT_ANALYSIS_OPTIONS = {
+    largeFileTokens: 2000,
+    warningFileTokens: 4000,
+    gitWindowDays: 90,
+};
+/** A convenience no-op rule used to keep the pipeline stable while built. */
+export function emptyFindings() {
+    return [];
+}
+//# sourceMappingURL=types.js.map

package/dist/analyzer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/analyzer/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,IAAI;IACvB,aAAa,EAAE,EAAE;CAClB,CAAC;AAqBF,6EAA6E;AAC7E,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * contextcheck CLI entry point.
+ *
+ * Wires the local-first pipeline to commands: analyze, snapshot and diff are
+ * functional; config remains a stub (handled by `.contextcheck.json`).
+ */
+import { Command } from "commander";
+export declare function analyzeAction(opts: {
+    verbose?: boolean;
+    json?: boolean;
+    compact?: boolean;
+    failOn?: string;
+}): Promise<void>;
+/** `contextcheck snapshot` — records current AI configuration + findings. */
+export declare function snapshotAction(): Promise<void>;
+/** `contextcheck diff [snapshot-id]` — compares a snapshot vs current state. */
+export declare function diffAction(from?: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+/** `contextcheck snapshot list` — lists stored snapshots. */
+export declare function snapshotListAction(): Promise<void>;
+export declare const program: Command;