@wrtnlabs/evidence 0.0.0

package/lib/adapters/c/CDeclarationForm.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Enumerates C source forms that can establish an Evidence declaration.
+ *
+ * Materialization uses the form to determine compatible repeats, ownership, and
+ * public address policy. Unsupported syntax is diagnosed by the scanner instead
+ * of being coerced into one of these categories.
+ */
+export type CDeclarationForm = "struct" | "union" | "enum" | "typedef" | "function" | "object" | "field" | "enumerator";

package/lib/adapters/c/CDeclarationForm.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/c/CDeclaratorKind.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Classifies the effective entity introduced by a supported C declarator.
+ *
+ * The scanner unwraps syntax that only changes type spelling and uses this
+ * discriminator to distinguish callable declarations from object declarations.
+ * It does not model the declaration's full C type.
+ */
+export type CDeclaratorKind = "direct" | "function" | "object";

package/lib/adapters/c/CDeclaratorKind.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/c/CDocumentation.d.ts

@@ -0,0 +1,12 @@
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ICDocumentation } from "./ICDocumentation";
+/**
+ * Reads C Doxygen documentation while masking embedded source examples.
+ *
+ * The C adapter uses this wrapper around the shared reader so Evidence tags in
+ * code and preformatted examples cannot be mistaken for documentation claims.
+ */
+export declare namespace CDocumentation {
+    function read(source: IEvidenceSourceFile, documentation: ICDocumentation, hostId: string): IEvidenceDocumentation;
+}

package/lib/adapters/c/CDocumentation.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+/**
+ * Reads C Doxygen documentation while masking embedded source examples.
+ *
+ * The C adapter uses this wrapper around the shared reader so Evidence tags in
+ * code and preformatted examples cannot be mistaken for documentation claims.
+ */
+var CDocumentation;
+(function (CDocumentation) {
+    function read(source, documentation, hostId) {
+        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, documentation.syntax);
+        if (!documentation.syntax.allowWithdrawal)
+            return parsed;
+        return { ...parsed, text: mask(parsed.text) };
+    }
+    CDocumentation.read = read;
+    function mask(input) {
+        const characters = input.split("");
+        for (const expression of [
+            /<(code|pre)\b[^>]*>[\s\S]*?<\/\1\s*>/giu,
+            /(?:@|\\)code\b[\s\S]*?(?:@|\\)endcode\b/giu,
+        ])
+            for (const match of input.matchAll(expression))
+                hide(characters, match.index, match.index + match[0].length);
+        return characters.join("");
+    }
+    function hide(characters, start, end) {
+        for (let index = start; index < end; ++index)
+            if (characters[index] !== "\n" && characters[index] !== "\r")
+                characters[index] = " ";
+    }
+})(CDocumentation || (exports.CDocumentation = CDocumentation = {}));

package/lib/adapters/c/CFileScanner.d.ts

@@ -0,0 +1,64 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ICFileAnalysis } from "./ICFileAnalysis";
+/**
+ * Extracts explicit C declarations and Doxygen without preprocessing source.
+ *
+ * It records physical declaration and attachment facts for `CAdapter` to
+ * reconcile; it never infers declarations from included or expanded source.
+ */
+export declare class CFileScanner {
+    private readonly session;
+    private readonly source;
+    private readonly declarations;
+    private readonly documentation;
+    private readonly carrierDocumentation;
+    private readonly diagnostics;
+    private readonly reported;
+    private readonly tags;
+    private readonly text;
+    private complete;
+    /**
+     * Creates one scanner bound to a live C parse session and source snapshot.
+     *
+     * Documentation is collected before declaration walking so adjacency can be
+     * decided against the original source positions.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Scans supported top-level C constructs into node-free file analysis.
+     *
+     * Unsupported public-surface syntax adds diagnostics and makes the returned
+     * analysis incomplete instead of silently omitting its declarations.
+     */
+    scan(): ICFileAnalysis;
+    private scanTopLevel;
+    private inertTopLevel;
+    private scanFunctionDefinition;
+    private scanExternalDeclaration;
+    private scanTypeDefinition;
+    private scanTag;
+    private scanFields;
+    private scanField;
+    private scanEnumerators;
+    private addRootDeclaration;
+    private addDeclaration;
+    private tagAddresses;
+    private canonicalAddress;
+    private documentationFor;
+    private adjacent;
+    private trailingAdjacent;
+    private collectDocumentation;
+    private lineFamily;
+    private attach;
+    private ensureDocumentation;
+    private unreadableDeclarator;
+    private firstConditional;
+    private conditional;
+    private macroDeclaration;
+    private preprocessorDirective;
+    private annotation;
+    private nodeKey;
+    private siteId;
+    private problem;
+}

package/lib/adapters/c/CFileScanner.js

@@ -0,0 +1,505 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CFileScanner = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const CSyntax_1 = require("./CSyntax");
+const SourceText_1 = require("../../internal/SourceText");
+/**
+ * Extracts explicit C declarations and Doxygen without preprocessing source.
+ *
+ * It records physical declaration and attachment facts for `CAdapter` to
+ * reconcile; it never infers declarations from included or expanded source.
+ */
+class CFileScanner {
+    session;
+    source;
+    declarations = [];
+    documentation = new Map();
+    carrierDocumentation = new Map();
+    diagnostics = [];
+    reported = new Set();
+    tags = new Map();
+    text;
+    complete = true;
+    /**
+     * Creates one scanner bound to a live C parse session and source snapshot.
+     *
+     * Documentation is collected before declaration walking so adjacency can be
+     * decided against the original source positions.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new SourceText_1.SourceText(source.content);
+        this.collectDocumentation();
+    }
+    /**
+     * Scans supported top-level C constructs into node-free file analysis.
+     *
+     * Unsupported public-surface syntax adds diagnostics and makes the returned
+     * analysis incomplete instead of silently omitting its declarations.
+     */
+    scan() {
+        const items = this.session.root.namedChildren;
+        const population = items.filter((item) => !this.inertTopLevel(item));
+        const guarded = population.length === 1 && population[0] !== undefined
+            ? CSyntax_1.CSyntax.guardedDeclarations(population[0])
+            : undefined;
+        for (const item of guarded ?? items)
+            this.scanTopLevel(item);
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: Array.from(this.documentation.values()),
+            diagnostics: this.diagnostics,
+            complete: this.complete,
+        };
+    }
+    scanTopLevel(item) {
+        switch (item.type) {
+            case "comment":
+            case "preproc_include":
+            case "preproc_def":
+            case "preproc_function_def":
+            case "_static_assert_declaration":
+            case "static_assert_declaration":
+                return;
+            case "function_definition":
+                this.scanFunctionDefinition(item);
+                return;
+            case "declaration":
+                this.scanExternalDeclaration(item);
+                return;
+            case "type_definition":
+                this.scanTypeDefinition(item);
+                return;
+            case "struct_specifier":
+            case "union_specifier":
+            case "enum_specifier":
+                this.scanTag(item, [], item, this.documentationFor(item));
+                return;
+            case "preproc_if":
+            case "preproc_ifdef":
+                this.conditional(item);
+                return;
+            case "preproc_call":
+                if (!CSyntax_1.CSyntax.isInertDirective(item))
+                    this.preprocessorDirective(item);
+                return;
+            case "expression_statement":
+                if (!CSyntax_1.CSyntax.isStaticAssertion(item))
+                    this.macroDeclaration(item);
+                return;
+            default:
+                this.problem("c-declaration-form", `C translation-unit form '${item.type}' is not classified by this adapter.`, "Add an explicit source-declaration rule before evaluating this file.", item);
+        }
+    }
+    inertTopLevel(node) {
+        return (node.type === "comment" ||
+            node.type === "preproc_include" ||
+            node.type === "preproc_def" ||
+            node.type === "preproc_function_def" ||
+            node.type === "_static_assert_declaration" ||
+            node.type === "static_assert_declaration" ||
+            CSyntax_1.CSyntax.isStaticAssertion(node) ||
+            CSyntax_1.CSyntax.isInertDirective(node));
+    }
+    scanFunctionDefinition(item) {
+        if (CSyntax_1.CSyntax.storage(item, "static"))
+            return;
+        const declarator = item.childForFieldName("declarator");
+        if (declarator === null) {
+            this.problem("c-function-declarator", "A C function definition has no statically readable function declarator.", "Use an ordinary named function definition supported by the pinned grammar.", item);
+            return;
+        }
+        const conditional = this.firstConditional(declarator);
+        if (conditional !== undefined)
+            this.conditional(conditional);
+        const shape = CSyntax_1.CSyntax.declarator(declarator);
+        if (shape === undefined || shape.kind !== "function") {
+            this.problem("c-function-declarator", "A C function definition has no statically readable function declarator.", "Use an ordinary named function definition supported by the pinned grammar.", item);
+            return;
+        }
+        this.addDeclaration(declarator, item, this.documentationFor(item), [this.session.range(item)], shape.name, "function", "function", [shape.name], [this.canonicalAddress([shape.name])], true);
+    }
+    scanExternalDeclaration(item) {
+        const conditional = this.firstConditional(item);
+        if (conditional !== undefined)
+            this.conditional(conditional);
+        const specifier = item.childForFieldName("type");
+        if (CSyntax_1.CSyntax.tagForm(specifier) !== null && specifier !== null)
+            this.scanTag(specifier, [], item, this.documentationFor(item));
+        if (CSyntax_1.CSyntax.storage(item, "static"))
+            return;
+        const documentation = this.documentationFor(item);
+        const declarators = CSyntax_1.CSyntax.declarators(item);
+        const first = declarators[0];
+        const header = first === undefined
+            ? this.session.range(item)
+            : this.text.range(item.startIndex, first.startIndex);
+        for (const declarator of declarators) {
+            const shape = CSyntax_1.CSyntax.declarator(declarator);
+            if (shape === undefined) {
+                this.unreadableDeclarator(declarator);
+                continue;
+            }
+            const functionDeclaration = shape.kind === "function";
+            this.addRootDeclaration(shape, item, documentation, [header, this.session.range(declarator)], functionDeclaration ? "function" : "property", functionDeclaration ? "function" : "object", functionDeclaration
+                ? false
+                : declarator.type === "init_declarator" ||
+                    !CSyntax_1.CSyntax.storage(item, "extern"));
+        }
+    }
+    scanTypeDefinition(item) {
+        const conditional = this.firstConditional(item);
+        if (conditional !== undefined)
+            this.conditional(conditional);
+        const documentation = this.documentationFor(item);
+        const declarators = CSyntax_1.CSyntax.declarators(item);
+        const first = declarators[0];
+        const header = first === undefined
+            ? this.session.range(item)
+            : this.text.range(item.startIndex, first.startIndex);
+        const shapes = declarators.flatMap((declarator) => {
+            const shape = CSyntax_1.CSyntax.declarator(declarator);
+            if (shape === undefined) {
+                this.unreadableDeclarator(declarator);
+                return [];
+            }
+            return [shape];
+        });
+        const specifier = item.childForFieldName("type");
+        const tag = CSyntax_1.CSyntax.tagForm(specifier);
+        const directAliases = Array.from(new Set(shapes.flatMap((shape) => shape.kind === "direct" ? [shape.name] : []))).sort(compare);
+        const owner = tag === null || specifier === null
+            ? undefined
+            : this.scanTag(specifier, directAliases, item, documentation);
+        for (const shape of shapes) {
+            if (owner !== undefined && shape.kind === "direct")
+                continue;
+            this.addRootDeclaration(shape, item, documentation, [header, this.session.range(shape.node)], "type", "typedef", true);
+        }
+    }
+    scanTag(specifier, directAliases, siteNode, documentation) {
+        const form = CSyntax_1.CSyntax.tagForm(specifier);
+        if (form === null)
+            return undefined;
+        const tagName = CSyntax_1.CSyntax.name(specifier.childForFieldName("name"));
+        const body = specifier.childForFieldName("body");
+        const aliases = Array.from(new Set(directAliases)).sort(compare);
+        const stored = tagName === undefined ? undefined : this.tags.get(`${form}:${tagName}`);
+        if (stored !== undefined && body === null && aliases.length === 0)
+            return stored;
+        if (tagName === undefined && aliases.length === 0)
+            return undefined;
+        const identityName = tagName === undefined ? aliases[0] : `${form} ${tagName}`;
+        if (identityName === undefined)
+            return undefined;
+        const addresses = this.tagAddresses(form, tagName, aliases);
+        const declaration = this.addDeclaration(specifier, siteNode, documentation, [this.session.range(specifier)], tagName ?? identityName, "type", form, [identityName], addresses, body !== null, undefined, tagName);
+        const context = {
+            declarationId: declaration.id,
+            identity: declaration.identity,
+        };
+        if (tagName !== undefined)
+            this.tags.set(`${form}:${tagName}`, context);
+        if (body === null)
+            return context;
+        if (form === "enum")
+            this.scanEnumerators(body, context);
+        else
+            this.scanFields(body, context);
+        return context;
+    }
+    scanFields(body, owner) {
+        for (const field of body.namedChildren)
+            switch (field.type) {
+                case "comment":
+                case "_static_assert_declaration":
+                case "static_assert_declaration":
+                    break;
+                case "field_declaration":
+                    this.scanField(field, owner);
+                    break;
+                case "preproc_if":
+                case "preproc_ifdef":
+                    this.conditional(field);
+                    break;
+                case "preproc_call":
+                    if (!CSyntax_1.CSyntax.isInertDirective(field))
+                        this.preprocessorDirective(field);
+                    break;
+                default:
+                    this.problem("c-field-form", `C aggregate member form '${field.type}' is not classified by this adapter.`, "Add an explicit aggregate-member rule before evaluating this type.", field);
+            }
+    }
+    scanField(item, owner) {
+        const documentation = this.documentationFor(item);
+        const specifier = item.childForFieldName("type");
+        const tag = CSyntax_1.CSyntax.tagForm(specifier);
+        const declarators = CSyntax_1.CSyntax.declarators(item);
+        if (tag !== null && specifier !== null && declarators.length === 0) {
+            const name = CSyntax_1.CSyntax.name(specifier.childForFieldName("name"));
+            if (name === undefined) {
+                const body = specifier.childForFieldName("body");
+                if (body !== null) {
+                    if (tag === "enum")
+                        this.scanEnumerators(body, owner);
+                    else
+                        this.scanFields(body, owner);
+                }
+            }
+            else
+                this.scanTag(specifier, [], item, documentation);
+            return;
+        }
+        if (tag !== null && specifier !== null)
+            this.scanTag(specifier, [], item, documentation);
+        const first = declarators[0];
+        const header = first === undefined
+            ? this.session.range(item)
+            : this.text.range(item.startIndex, first.startIndex);
+        for (const declarator of declarators) {
+            const shape = CSyntax_1.CSyntax.declarator(declarator);
+            if (shape === undefined) {
+                this.unreadableDeclarator(declarator);
+                continue;
+            }
+            this.addDeclaration(declarator, item, documentation, [header, this.session.range(declarator)], shape.name, "property", "field", [...owner.identity, shape.name], [], true, owner.declarationId);
+        }
+    }
+    scanEnumerators(body, owner) {
+        for (const item of body.namedChildren)
+            switch (item.type) {
+                case "comment":
+                    break;
+                case "enumerator": {
+                    const name = CSyntax_1.CSyntax.name(item.childForFieldName("name"));
+                    if (name === undefined) {
+                        this.unreadableDeclarator(item);
+                        break;
+                    }
+                    this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, "property", "enumerator", [...owner.identity, name], [], true, owner.declarationId);
+                    break;
+                }
+                case "preproc_if":
+                case "preproc_ifdef":
+                    this.conditional(item);
+                    break;
+                case "preproc_call":
+                    if (!CSyntax_1.CSyntax.isInertDirective(item))
+                        this.preprocessorDirective(item);
+                    break;
+                default:
+                    this.problem("c-enumerator-form", `C enum member form '${item.type}' is not classified by this adapter.`, "Add an explicit enumerator rule before evaluating this enum.", item);
+            }
+    }
+    addRootDeclaration(shape, siteNode, documentation, content, symbol, form, definition) {
+        return this.addDeclaration(shape.node, siteNode, documentation, content, shape.name, symbol, form, [shape.name], [this.canonicalAddress([shape.name])], definition);
+    }
+    addDeclaration(item, siteNode, documentation, content, name, symbol, form, identity, addresses, definition, ownerDeclarationId, tagName) {
+        const start = Math.min(siteNode.startIndex, ...documentation.map((entry) => entry.range.start.offset));
+        const end = Math.max(siteNode.endIndex, ...documentation.map((entry) => entry.range.end.offset));
+        const site = {
+            id: this.siteId(siteNode),
+            file: this.source.physicalPath,
+            range: this.text.range(start, end),
+            content,
+        };
+        const declaration = {
+            id: `c:${this.source.id}:declaration:${form}:${item.startIndex}:${name}`,
+            name,
+            symbol,
+            form,
+            identity,
+            addresses,
+            site,
+            definition,
+            ...(ownerDeclarationId === undefined ? {} : { ownerDeclarationId }),
+            ...(tagName === undefined ? {} : { tagName }),
+        };
+        this.declarations.push(declaration);
+        for (const entry of documentation)
+            this.attach(entry, declaration.id, site.id);
+        return declaration;
+    }
+    tagAddresses(form, tagName, aliases) {
+        const addresses = aliases.map((alias) => this.canonicalAddress([alias]));
+        if (tagName === undefined)
+            return addresses;
+        const exact = `${form} ${tagName}`;
+        return [
+            this.canonicalAddress([exact]),
+            {
+                segments: [tagName],
+                canonical: false,
+                aliasPrefixes: [[tagName]],
+            },
+            ...addresses,
+        ];
+    }
+    canonicalAddress(segments) {
+        return { segments, canonical: true, aliasPrefixes: [] };
+    }
+    documentationFor(node) {
+        const output = [];
+        const previous = node.previousNamedSibling;
+        if (previous !== null && CSyntax_1.CSyntax.isDoxygen(previous)) {
+            const documentation = this.carrierDocumentation.get(this.nodeKey(previous));
+            if (documentation !== undefined &&
+                !CSyntax_1.CSyntax.isTrailingDoxygen(previous) &&
+                this.adjacent(documentation.range.end.offset, node.startIndex, true))
+                output.push(documentation);
+        }
+        const next = node.nextNamedSibling;
+        if (next !== null && CSyntax_1.CSyntax.isTrailingDoxygen(next)) {
+            const documentation = this.carrierDocumentation.get(this.nodeKey(next));
+            if (documentation !== undefined &&
+                this.trailingAdjacent(node, documentation.range.start.offset, next.startPosition.row))
+                output.push(documentation);
+        }
+        return output;
+    }
+    adjacent(start, end, allowNewline) {
+        const gap = this.source.content.slice(start, end);
+        return (/^\s*$/u.test(gap) &&
+            !/\r?\n[ \t]*\r?\n/u.test(gap) &&
+            (allowNewline || !/[\r\n]/u.test(gap)));
+    }
+    trailingAdjacent(node, end, commentRow) {
+        if (node.endPosition.row !== commentRow)
+            return false;
+        const gap = this.source.content.slice(node.endIndex, end);
+        if (node.type === "enumerator")
+            return /^[ \t]*,[ \t]*$/u.test(gap);
+        if (node.type === "struct_specifier" ||
+            node.type === "union_specifier" ||
+            node.type === "enum_specifier")
+            return /^[ \t]*;[ \t]*$/u.test(gap);
+        return /^[ \t]*$/u.test(gap);
+    }
+    collectDocumentation() {
+        const comments = this.session.root
+            .descendantsOfType("comment")
+            .sort((left, right) => left.startIndex - right.startIndex);
+        const consumed = new Set();
+        for (const first of comments) {
+            if (consumed.has(this.nodeKey(first)))
+                continue;
+            const sequence = [first];
+            consumed.add(this.nodeKey(first));
+            let last = first;
+            if (first.text.startsWith("//") && !CSyntax_1.CSyntax.isTrailingDoxygen(first)) {
+                let next = last.nextNamedSibling;
+                while (next !== null &&
+                    next.type === "comment" &&
+                    this.lineFamily(next) === this.lineFamily(first) &&
+                    next.startPosition.column === first.startPosition.column &&
+                    this.adjacent(last.endIndex, next.startIndex, true)) {
+                    sequence.push(next);
+                    consumed.add(this.nodeKey(next));
+                    last = next;
+                    next = last.nextNamedSibling;
+                }
+            }
+            const range = this.text.range(first.startIndex, last.endIndex);
+            const syntax = CSyntax_1.CSyntax.comment(first);
+            const supported = CSyntax_1.CSyntax.isDoxygen(first);
+            const raw = EvidenceDocumentation_1.EvidenceDocumentation.read(this.source.content, "c-probe", range, syntax).text;
+            if (!supported && !this.annotation(raw))
+                continue;
+            const documentation = this.ensureDocumentation(range, syntax);
+            for (const comment of sequence)
+                this.carrierDocumentation.set(this.nodeKey(comment), documentation);
+        }
+        for (const literal of this.session.root.descendantsOfType("string_literal")) {
+            const syntax = CSyntax_1.CSyntax.string(literal);
+            if (syntax === undefined)
+                continue;
+            const range = this.session.range(literal);
+            const raw = EvidenceDocumentation_1.EvidenceDocumentation.read(this.source.content, "c-probe", range, syntax).text;
+            if (this.annotation(raw))
+                this.ensureDocumentation(range, syntax);
+        }
+    }
+    lineFamily(node) {
+        if (node.text.startsWith("///<"))
+            return "///<";
+        if (node.text.startsWith("//!<"))
+            return "//!<";
+        if (node.text.startsWith("///"))
+            return "///";
+        if (node.text.startsWith("//!"))
+            return "//!";
+        return "//";
+    }
+    attach(documentation, declarationId, siteId) {
+        if (!documentation.attachments.some((attachment) => attachment.declarationId === declarationId &&
+            attachment.siteId === siteId))
+            documentation.attachments.push({ declarationId, siteId });
+    }
+    ensureDocumentation(range, syntax) {
+        const key = `${range.start.offset}:${range.end.offset}`;
+        let documentation = this.documentation.get(key);
+        if (documentation === undefined) {
+            documentation = {
+                id: `c:${this.source.id}:documentation:${key}`,
+                range,
+                syntax,
+                attachments: [],
+            };
+            this.documentation.set(key, documentation);
+        }
+        return documentation;
+    }
+    unreadableDeclarator(node) {
+        this.problem("c-declarator-name", "A selected C declarator has no statically readable identifier.", "Use one named declarator supported by the pinned grammar.", node);
+    }
+    firstConditional(node) {
+        for (const type of ["preproc_if", "preproc_ifdef"]) {
+            const conditional = node.descendantsOfType(type)[0];
+            if (conditional !== undefined)
+                return conditional;
+        }
+        return undefined;
+    }
+    conditional(node) {
+        this.problem("c-preprocessor-conditional", "Conditional preprocessing can change the selected C declaration population.", "Select generated preprocessed source or remove declaration-position conditional branches.", node);
+    }
+    macroDeclaration(node) {
+        this.problem("c-macro-declaration", "A declaration-position macro invocation can generate an unknown C surface.", "Select the generated declaration source or replace the invocation with explicit declarations.", node);
+    }
+    preprocessorDirective(node) {
+        this.problem("c-preprocessor-directive", "A selected C preprocessor directive can change declaration semantics.", "Select generated source or add an explicit rule for this directive before evaluating coverage.", node);
+    }
+    annotation(raw) {
+        return /(?:^|[\r\n])[ \t]*@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(raw);
+    }
+    nodeKey(node) {
+        return `${node.startIndex}:${node.endIndex}`;
+    }
+    siteId(node) {
+        return `c:${this.source.id}:site:${this.nodeKey(node)}`;
+    }
+    problem(code, message, repair, node) {
+        const key = `${code}:${node.startIndex}:${node.endIndex}`;
+        if (this.reported.has(key))
+            return;
+        this.reported.add(key);
+        this.complete = false;
+        this.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.CFileScanner = CFileScanner;
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/lib/adapters/c/CSyntax.d.ts

@@ -0,0 +1,24 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { CDeclarationForm } from "./CDeclarationForm";
+import type { ICDeclaratorShape } from "./ICDeclaratorShape";
+/**
+ * Provides C grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * CFileScanner uses these syntactic facts to construct declarations and
+ * documentation records without assigning public-surface policy to this namespace.
+ */
+export declare namespace CSyntax {
+    function name(node: Node | null): string | undefined;
+    function declarators(node: Node): Node[];
+    function declarator(node: Node): ICDeclaratorShape | undefined;
+    function tagForm(node: Node | null): Extract<CDeclarationForm, "struct" | "union" | "enum"> | null;
+    function storage(node: Node, value: string): boolean;
+    function isStaticAssertion(node: Node): boolean;
+    function guardedDeclarations(node: Node): Node[] | undefined;
+    function isInertDirective(node: Node): boolean;
+    function isDoxygen(node: Node): boolean;
+    function isTrailingDoxygen(node: Node): boolean;
+    function comment(node: Node): IEvidenceCommentSyntax;
+    function string(node: Node): IEvidenceCommentSyntax | undefined;
+}