@kernlang/review 3.5.6 → 3.5.7

package/dist/config-files/markdown.js

@@ -0,0 +1,262 @@
+/**
+ * Markdown analyzer + outline extractor — self-contained line scanner.
+ *
+ * Replaces the previous `mdast-util-from-markdown` dependency (which pulled
+ * ~30 transitive `micromark-*` packages) with a focused state machine. The
+ * tradeoff is deliberate: this is NOT a CommonMark parser. It is a config /
+ * docs hygiene scanner that covers exactly what kern-sight and kern-guard
+ * need today —
+ *
+ *   • ATX headings (`#` through `######`) outside fenced code
+ *   • Image syntax `![alt](url)` on a non-code line
+ *   • Fenced-code awareness (backtick and tilde fences, length-matched)
+ *   • Outline tree built from heading levels + slugs
+ *
+ * What we deliberately do NOT handle, because feature surface stays small:
+ *
+ *   • Setext headings (`===` / `---` underlines) — uncommon in this codebase
+ *   • Inline HTML headings (`<h1>…</h1>`)
+ *   • Reference-style images (`![alt][label]` + `[label]: url`)
+ *   • Indented (4-space) code blocks
+ *   • Tab handling beyond the obvious cases
+ *   • Inline code spans (`` `![](url)` ``) — image syntax inside backtick
+ *     spans on an otherwise non-fenced line can trip the image-alt rule.
+ *     False positives here surface as `md/image-missing-alt` on the URL
+ *     inside the span. Acceptable for a hygiene scanner; if it becomes
+ *     a real noise source, suppress with `kern-ignore` directives.
+ *
+ * If a doc uses those forms, findings on it are best-effort. The point is
+ * predictable diagnostics for the common 95% case, not full CommonMark
+ * fidelity, and to keep `@kernlang/review` trending toward zero dependencies.
+ *
+ * Two outputs from a single pass:
+ *
+ *   1. ReviewFinding[] — structural issues (skipped heading levels, missing
+ *      image alt text). Flow through the engine's standard pipeline so both
+ *      kern-sight (editor diagnostics) and kern-guard (Check annotations)
+ *      consume them without API changes.
+ *
+ *   2. MarkdownOutline — heading tree shaped for kern-sight's Current File
+ *      webview. Exported separately because kern-guard has no use for it
+ *      (only findings get posted to GitHub); keeping it off the engine's
+ *      ReviewReport keeps the worker-side surface minimal.
+ *
+ * Fingerprint policy: structural keys (heading path, image alt-text URL),
+ * NEVER line numbers, so kern-guard's baseline dedup does not re-post on
+ * whitespace edits.
+ */
+/** GitHub-style heading slug — lowercase, strip non-letter / non-digit
+ *  punctuation across the full Unicode range (so `Café`, `中文`, `Привет`
+ *  survive), then replace each whitespace char (not runs) with one hyphen.
+ *  Per-char (not collapsed) replacement matches GitHub's behavior: "API &
+ *  Usage" becomes "api--usage" because `&` is dropped while both
+ *  surrounding spaces survive as separate hyphens. */
+function slugify(text) {
+    return (text
+        .toLowerCase()
+        // Allow Unicode letters, digits, underscores (GitHub keeps `_` in slugs),
+        // whitespace (collapsed to hyphens below), and hyphens.
+        .replace(/[^\p{L}\p{N}_\s-]/gu, '')
+        .trim()
+        .replace(/\s/g, '-'));
+}
+// Image syntax: `![alt](url)`. Allowed: empty alt, alt with spaces and
+// most punctuation EXCEPT `]`, URL with most chars EXCEPT `)`. Reference-style
+// images (`![alt][label]`) are intentionally not matched — see header comment.
+const IMAGE_RE = /!\[([^\]\n]*)\]\(([^)\n]*)\)/g;
+/**
+ * Single-pass scanner. Walks source line by line, tracks open fenced code
+ * blocks (backtick or tilde fences), collects ATX headings + image syntax
+ * from non-code lines.
+ */
+function scanMarkdown(source) {
+    const headings = [];
+    const images = [];
+    // Fenced code state. When inside a fence, both heading and image
+    // detection are suppressed. The closing fence must match the opening
+    // character AND be at least as long as the opener (CommonMark §4.5).
+    let inFence = false;
+    let fenceChar = null;
+    let fenceLen = 0;
+    // Split keeping line numbers 1-based. \r\n is normalized to \n via split
+    // on /\r?\n/ so Windows line endings don't break anything.
+    const lines = source.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNo = i + 1;
+        // Fence detection per CommonMark §4.5:
+        //   - up to 3 spaces of leading indent (NOT arbitrary tabs/whitespace —
+        //     a 4-space-indented `` ``` `` is part of an indented code block, not
+        //     a fence, so it must NOT trigger fence state)
+        //   - opening fences may carry an info string after the marker run
+        //     (`` ```js ``); closing fences may have ONLY trailing whitespace.
+        //
+        // Match opening and closing with different regexes so a line like
+        // ` ```text ` while already in a fence doesn't bogusly close it. Both
+        // anchor on `^ {0,3}` so a 4-space indent is left to the
+        // indented-code-block class (which we don't model — those lines simply
+        // don't satisfy heading/image detection either, so they're safe).
+        const openFenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
+        const closeFenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
+        if (inFence) {
+            if (closeFenceMatch) {
+                const ch = closeFenceMatch[1].charAt(0);
+                if (ch === fenceChar && closeFenceMatch[1].length >= fenceLen) {
+                    inFence = false;
+                    fenceChar = null;
+                    fenceLen = 0;
+                }
+            }
+            // Anything else inside a fence is ignored for headings/images.
+            continue;
+        }
+        if (openFenceMatch) {
+            inFence = true;
+            fenceChar = openFenceMatch[1].charAt(0);
+            fenceLen = openFenceMatch[1].length;
+            continue;
+        }
+        // ATX heading: optional ≤3 spaces of indent, 1-6 `#`, REQUIRED space
+        // after (per CommonMark) unless the line is just `#` chars. We also
+        // strip optional trailing `# …` decoration.
+        const headingMatch = line.match(/^ {0,3}(#{1,6})(?:\s+(.*?))?(?:\s+#+\s*)?\s*$/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            // Use the raw heading text as-is — do NOT globally strip ``, *, _
+            // characters. That would turn `API_KEY` into `APIKEY` (breaking
+            // outline labels) and was a regression vs the prior mdast-backed
+            // implementation. A proper inline-span parser would distinguish
+            // paired delimiters from literal underscores; we accept that the
+            // outline shows raw markdown for headings with inline emphasis and
+            // leave true delimiter handling out of scope (matches the module's
+            // "hygiene scanner, not CommonMark" contract).
+            const text = (headingMatch[2] ?? '').trim();
+            const slug = slugify(text) || `heading-${lineNo}`;
+            // startCol = where the first `#` sits.
+            const startCol = line.length - line.replace(/^ */, '').length + 1;
+            headings.push({
+                level,
+                text,
+                slug,
+                line: lineNo,
+                startCol,
+                endCol: line.length + 1,
+            });
+            continue;
+        }
+        // Image syntax. matchAll gives us all occurrences on the line with
+        // their positions; we collect each as a ScanImage.
+        for (const m of line.matchAll(IMAGE_RE)) {
+            const idx = m.index ?? 0;
+            images.push({
+                alt: m[1] ?? '',
+                url: (m[2] ?? '').trim(),
+                line: lineNo,
+                startCol: idx + 1,
+                endCol: idx + m[0].length + 1,
+            });
+        }
+    }
+    return { headings, images };
+}
+function makeSpan(filePath, line, startCol, endCol) {
+    return { file: filePath, startLine: line, startCol, endLine: line, endCol };
+}
+/**
+ * Parse markdown once and emit both findings and outline. Internal — public
+ * entry points (`reviewMarkdownFile`, `extractMarkdownOutline`) share this.
+ */
+function analyze(source, filePath) {
+    const { headings, images } = scanMarkdown(source);
+    const findings = [];
+    // ── Skipped heading levels ──────────────────────────────────────────
+    // h1 → h3 is a structural smell (screen-readers, TOC generators get confused).
+    // The first heading sets the baseline; after that, level must not jump by
+    // more than 1 deeper. Going shallower (h3 → h2) is always fine.
+    //
+    // The running heading path tracks (level, slug) tuples — NOT just slugs by
+    // index. The naive `length >= depth` pop is wrong when levels are skipped:
+    // after `# A` + `### B`, the stack length is 2 but B is at depth 3, so a
+    // subsequent sibling `### B2` would not pop B and would instead nest
+    // *under* B. That would make B2's fingerprint depend on B's text, so
+    // renaming B would change B2's fingerprint — kern-guard would re-post B2
+    // as a "new" finding on the next PR. Comparing on `.level` avoids that.
+    let prevLevel = null;
+    const headingPath = [];
+    for (const h of headings) {
+        while (headingPath.length > 0 && headingPath[headingPath.length - 1].level >= h.level) {
+            headingPath.pop();
+        }
+        headingPath.push({ level: h.level, slug: h.slug });
+        if (prevLevel !== null && h.level > prevLevel + 1) {
+            const ruleId = 'md/skipped-heading-level';
+            const path = headingPath.map((p) => p.slug).join('/');
+            findings.push({
+                source: 'kern',
+                ruleId,
+                severity: 'warning',
+                category: 'structure',
+                message: `Heading jumps from h${prevLevel} to h${h.level} — skipping levels breaks document outline and assistive tech navigation.`,
+                primarySpan: makeSpan(filePath, h.line, h.startCol, h.endCol),
+                confidence: 95,
+                fingerprint: `${ruleId}:${path}`,
+            });
+        }
+        prevLevel = h.level;
+    }
+    // ── Images missing alt text ─────────────────────────────────────────
+    // Empty alt text on an image is an a11y red flag. Decorative images
+    // should use alt="" intentionally; the scanner can't distinguish, so we
+    // flag all empty-alt images and let the author confirm/suppress.
+    for (let i = 0; i < images.length; i++) {
+        const img = images[i];
+        const alt = img.alt.trim();
+        if (alt.length === 0) {
+            const ruleId = 'md/image-missing-alt';
+            // Fingerprint by URL (stable across line shifts); falls back to a
+            // sequence-based key only if the image has no URL at all.
+            const key = img.url || `idx-${i}`;
+            findings.push({
+                source: 'kern',
+                ruleId,
+                severity: 'warning',
+                category: 'structure',
+                message: `Image is missing alt text${img.url ? ` (\`${img.url}\`)` : ''}. Provide a description, or use \`![](…)\` only for purely decorative images.`,
+                primarySpan: makeSpan(filePath, img.line, img.startCol, img.endCol),
+                confidence: 90,
+                fingerprint: `${ruleId}:${key}`,
+            });
+        }
+    }
+    // ── Build outline ───────────────────────────────────────────────────
+    const flat = headings.map((h) => ({
+        level: h.level,
+        text: h.text,
+        slug: h.slug,
+        line: h.line,
+        children: [],
+    }));
+    // Nest into a tree by level — each heading owns subsequent deeper-level
+    // headings until a shallower heading closes the chain. Standard outline algo.
+    const outlineTree = [];
+    const stack = [];
+    for (const h of flat) {
+        while (stack.length > 0 && stack[stack.length - 1].level >= h.level)
+            stack.pop();
+        if (stack.length === 0)
+            outlineTree.push(h);
+        else
+            stack[stack.length - 1].children.push(h);
+        stack.push(h);
+    }
+    return { findings, outline: { flat, tree: outlineTree } };
+}
+/** Entry point for the engine dispatcher — findings only. */
+export function reviewMarkdownFile(source, filePath) {
+    return analyze(source, filePath).findings;
+}
+/** Public outline extractor — kern-sight only. */
+export function extractMarkdownOutline(source) {
+    return analyze(source, '<inline>').outline;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/config-files/markdown.js.map

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

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export type { ConceptRule, ConceptRuleContext } from './concept-rules/index.js';
 export { runConceptRules } from './concept-rules/index.js';
 export type { ConfidenceGraph, ConfidenceNode, ConfidenceSpec, ConfidenceSummary, DuplicateNameEntry, MultiFileConfidenceGraph, NeedsEntry, SerializedConfidenceGraph, } from './confidence.js';
 export { buildConfidenceGraph, buildMultiFileConfidenceGraph, computeConfidenceSummary, parseConfidence, propagateConfidence, resolveBaseConfidence, serializeGraph, } from './confidence.js';
+export { extractMarkdownOutline, type MarkdownOutline, type MarkdownOutlineHeading } from './config-files/markdown.js';
 export { structuralDiff } from './differ.js';
 export { evaluateReviewReports, formatReviewEvalSummary, normalizeReviewEvalManifest, type ReviewEvalCase, type ReviewEvalCaseConfig, type ReviewEvalCaseResult, type ReviewEvalExpectations, type ReviewEvalFindingExpectation, type ReviewEvalManifest, type ReviewEvalRunMetadata, type ReviewEvalSummary, summarizeReviewEvalResults, } from './eval.js';
 export { linkToNodes, runESLint, runTSCDiagnostics, runTSCDiagnosticsFromPaths } from './external-tools.js';
@@ -104,7 +105,7 @@ export declare function extractConceptsForGraph(filePaths: string[]): Map<string
 /**
  * Review a single file. Auto-detects language from extension.
  * Uses a filesystem-backed ts-morph Project for type-aware analysis.
- * Supports: .ts, .tsx, .py, .kern
+ * Supports: .ts, .tsx, .py, .kern, .json, .jsonc
  */
 export declare function reviewFile(filePath: string, config?: ReviewConfig): ReviewReport;
 /**

package/dist/index.js

@@ -34,6 +34,9 @@ import { buildCallGraph } from './call-graph.js';
 import { runConceptRules } from './concept-rules/index.js';
 import { isAuthEndpointTarget, isWorkerContextFile } from './concept-rules/unguarded-effect.js';
 import { isTransportPrimitiveCarveOut } from './concept-rules/unrecovered-effect.js';
+import { isEnvFile, reviewEnvFile } from './config-files/env.js';
+import { reviewJsonFile } from './config-files/json.js';
+import { reviewMarkdownFile } from './config-files/markdown.js';
 import { structuralDiff } from './differ.js';
 import { runTSCDiagnostics } from './external-tools.js';
 import { buildFileContextMap } from './file-context.js';
@@ -150,6 +153,7 @@ export { buildCallGraph } from './call-graph.js';
 export { runConceptRules } from './concept-rules/index.js';
 // Confidence layer
 export { buildConfidenceGraph, buildMultiFileConfidenceGraph, computeConfidenceSummary, parseConfidence, propagateConfidence, resolveBaseConfidence, serializeGraph, } from './confidence.js';
+export { extractMarkdownOutline } from './config-files/markdown.js';
 export { structuralDiff } from './differ.js';
 export { evaluateReviewReports, formatReviewEvalSummary, normalizeReviewEvalManifest, summarizeReviewEvalResults, } from './eval.js';
 export { linkToNodes, runESLint, runTSCDiagnostics, runTSCDiagnosticsFromPaths } from './external-tools.js';
@@ -321,8 +325,24 @@ const REVIEWABLE_EXTENSIONS = new Set([
     '.kern',
     '.py',
     '.vue',
+    // Config-file analyzers — parallel non-ts-morph path (config-files/*.ts).
+    // Findings flow through the same ReviewFinding pipeline so kern-sight and
+    // kern-guard consume them without API changes.
+    '.json',
+    '.jsonc',
+    '.md',
 ]);
+/** Files routed to the config-files analyzers, bypassing ts-morph entirely.
+ *  Includes extension-keyed analyzers (.json/.jsonc/.md) plus basename-keyed
+ *  analyzers (`.env`, `.env.local`, `.env.production`, …). */
+function isConfigFile(filePath) {
+    return filePath.endsWith('.json') || filePath.endsWith('.jsonc') || filePath.endsWith('.md') || isEnvFile(filePath);
+}
 export function isReviewableFile(filePath) {
+    // Basename-keyed analyzers come first — `.env.local` would yield extension
+    // `.local` under the simple lastIndexOf shortcut and be misclassified.
+    if (isEnvFile(filePath))
+        return true;
     const dot = filePath.lastIndexOf('.');
     if (dot === -1)
         return false;
@@ -380,10 +400,48 @@ function emptyReport(filePath) {
         },
     };
 }
+/**
+ * Build a ReviewReport for a config-file (.json / .jsonc) source. Bypasses
+ * ts-morph entirely — config analyzers emit ReviewFindings directly. Stats
+ * are minimal because IR/token reduction is meaningless for these files.
+ */
+function reviewConfigFileSource(source, filePath) {
+    let findings = [];
+    // Basename-keyed env check FIRST — `.env.md` / `.env.json` would otherwise
+    // route to the markdown/JSON analyzer because `endsWith` would match. This
+    // mirrors the basename-first ordering already used in `isReviewableFile`.
+    if (isEnvFile(filePath)) {
+        findings = reviewEnvFile(source, filePath);
+    }
+    else if (filePath.endsWith('.jsonc') || filePath.endsWith('.json')) {
+        // Check `.jsonc` before `.json` — `.jsonc` also satisfies `endsWith('.json')`
+        // and we want the JSONC dispatch to be explicit rather than rely on the
+        // dialect-detection re-check inside `reviewJsonFile` to bail us out.
+        findings = reviewJsonFile(source, filePath);
+    }
+    else if (filePath.endsWith('.md')) {
+        findings = reviewMarkdownFile(source, filePath);
+    }
+    return {
+        filePath,
+        inferred: [],
+        templateMatches: [],
+        findings,
+        stats: {
+            totalLines: source.split('\n').length,
+            coveredLines: 0,
+            coveragePct: 0,
+            totalTsTokens: 0,
+            totalKernTokens: 0,
+            reductionPct: 0,
+            constructCount: 0,
+        },
+    };
+}
 /**
  * Review a single file. Auto-detects language from extension.
  * Uses a filesystem-backed ts-morph Project for type-aware analysis.
- * Supports: .ts, .tsx, .py, .kern
+ * Supports: .ts, .tsx, .py, .kern, .json, .jsonc
  */
 export function reviewFile(filePath, config) {
     if (!isReviewableFile(filePath))
@@ -392,7 +450,7 @@ export function reviewFile(filePath, config) {
     // Resolve the effective tsconfig up-front so both the cache key and the ts-morph Project see the
     // same path. If we only discovered it later inside reviewSourceWithProject, adding or changing the
     // nearest tsconfig without editing the source would serve stale cached findings.
-    const effectiveConfig = config?.tsConfigFilePath || filePath.endsWith('.kern') || filePath.endsWith('.py')
+    const effectiveConfig = config?.tsConfigFilePath || filePath.endsWith('.kern') || filePath.endsWith('.py') || isConfigFile(filePath)
         ? config
         : { ...(config ?? {}), tsConfigFilePath: findTsConfig(dirname(filePath)) };
     let key;
@@ -403,7 +461,10 @@ export function reviewFile(filePath, config) {
             return cached;
     }
     let report;
-    if (filePath.endsWith('.kern')) {
+    if (isConfigFile(filePath)) {
+        report = reviewConfigFileSource(source, filePath);
+    }
+    else if (filePath.endsWith('.kern')) {
         report = reviewKernSource(source, filePath, effectiveConfig);
     }
     else if (filePath.endsWith('.py')) {