@wrtnlabs/evidence 0.0.0

package/lib/adapters/objc/IObjcDeclaration.d.ts

@@ -0,0 +1,79 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { ObjcDeclarationForm } from "./ObjcDeclarationForm";
+/**
+ * Represents one Objective-C declaration before interface and implementation reconciliation.
+ *
+ * The adapter keeps declarations from headers, implementations, categories, and
+ * extensions distinct until it can establish the one public semantic identity.
+ */
+export interface IObjcDeclaration {
+    /**
+     * Physical declaration identity within the snapshot.
+     *
+     * Reconciliation uses this value to retain each contributing source site.
+     */
+    id: string;
+    /**
+     * Exact declaration name, including selector punctuation.
+     *
+     * Selector colons and method prefixes remain literal identity spelling.
+     */
+    name: string;
+    /**
+     * Public programming selector.
+     *
+     * Population selection uses this category independently of source form.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Source form governing exposure and merging.
+     *
+     * Interfaces, implementations, and extensions follow distinct publication rules.
+     */
+    form: ObjcDeclarationForm;
+    /**
+     * Segmented identity in the configured declared-source boundary.
+     *
+     * This semantic path remains independent of public accessor spelling.
+     */
+    identity: string[];
+    /**
+     * Segmented file-qualified public accessor.
+     *
+     * Published addresses combine these literal segments with each selected file.
+     */
+    address: string[];
+    /**
+     * Original source declaration and fingerprint content ranges.
+     *
+     * Merged units preserve every site that contributes semantic content.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Whether this declaration participates in the public inventory after reconciliation.
+     *
+     * Private records can still become merge sites for a separately public identity.
+     */
+    public: boolean;
+    /**
+     * Permits an implementation or extension site to join a public identity.
+     *
+     * The flag never makes a private declaration public by itself; it authorizes
+     * reconciliation with the separately extracted interface declaration.
+     */
+    merge: boolean;
+    /**
+     * Marks a body or nominal implementation site that must be unique.
+     *
+     * Multiple declarations can describe a selector, but conflicting definitions
+     * leave the analysis incomplete rather than choosing an arbitrary site.
+     */
+    definition: boolean;
+    /**
+     * Physical owner declaration, reconciled to a semantic parent later.
+     *
+     * Omission denotes a root declaration in the selected source.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/objc/IObjcDeclaration.js

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

package/lib/adapters/objc/IObjcDocumentation.d.ts

@@ -0,0 +1,35 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IObjcDocumentationAttachment } from "./IObjcDocumentationAttachment";
+/**
+ * Represents a Doxygen documentation carrier or unsupported annotation-bearing comment.
+ *
+ * Attachment is determined before interface and implementation sites merge, so
+ * tagged ordinary comments remain available for an accurate host diagnostic.
+ */
+export interface IObjcDocumentation {
+    /**
+     * Stable physical carrier identifier.
+     *
+     * It keeps this comment distinct before its attachments are reconciled.
+     */
+    id: string;
+    /**
+     * Original UTF-16 range, including comment delimiters.
+     *
+     * Documentation mapping and host coordinates use this unmodified source span.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Mapped comment delimiters and withdrawal eligibility.
+     *
+     * Tag parsing uses the syntax mapping to preserve carrier-specific boundaries.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Declaration sites receiving this carrier.
+     *
+     * Each attachment retains its physical owner before semantic-unit merging.
+     */
+    attachments: IObjcDocumentationAttachment[];
+}

package/lib/adapters/objc/IObjcDocumentation.js

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

package/lib/adapters/objc/IObjcDocumentationAttachment.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Connects one Doxygen carrier to a physical Objective-C declaration site.
+ *
+ * Interface and implementation records may later share a semantic unit, but
+ * this attachment retains the exact source site that owns the annotation.
+ */
+export interface IObjcDocumentationAttachment {
+    /**
+     * Physical declaration receiving the documentation.
+     *
+     * The adapter resolves this extraction ID to its published unit when possible.
+     */
+    declarationId: string;
+    /**
+     * Eligible declaration site containing the carrier.
+     *
+     * This retains the exact source host when declarations later merge.
+     */
+    siteId: string;
+}

package/lib/adapters/objc/IObjcDocumentationAttachment.js

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

package/lib/adapters/objc/IObjcFileAnalysis.d.ts

@@ -0,0 +1,43 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IObjcDeclaration } from "./IObjcDeclaration";
+import type { IObjcDocumentation } from "./IObjcDocumentation";
+/**
+ * Holds the node-free Objective-C extraction retained after a parse session closes.
+ *
+ * Interface and implementation sites are reconciled only after every selected
+ * source is scanned, while this record keeps their physical provenance intact.
+ */
+export interface IObjcFileAnalysis {
+    /**
+     * Snapshot source and its logical aliases.
+     *
+     * Its physical path anchors sites while aliases supply published files.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Physical declaration sites before public identity reconciliation.
+     *
+     * Later materialization merges compatible interface and implementation records.
+     */
+    declarations: IObjcDeclaration[];
+    /**
+     * Attached and unsupported documentation carriers.
+     *
+     * Unsupported tagged carriers remain available for actionable diagnostics.
+     */
+    documentation: IObjcDocumentation[];
+    /**
+     * Actionable extraction and parser failures.
+     *
+     * Consumers retain these findings instead of accepting a smaller inventory.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether all surface-affecting Objective-C forms were classified.
+     *
+     * A false value protects coverage from incomplete header or implementation
+     * extraction by propagating the uncertainty into the final inventory.
+     */
+    complete: boolean;
+}

package/lib/adapters/objc/IObjcFileAnalysis.js

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

package/lib/adapters/objc/ObjcAdapter.d.ts

@@ -0,0 +1,100 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Extracts Objective-C public declarations into merged units and comment hosts.
+ *
+ * Interface, category, and implementation records require a shared ownership model
+ * before documentation can be attributed to semantic API subjects. The adapter
+ * retains each physical site while normalizing published identities and preserving
+ * failures that prevent complete extraction.
+ */
+export declare class ObjcAdapter implements IEvidenceAdapter {
+    /**
+     * Configured language discriminator for Objective-C extraction.
+     *
+     * It selects Objective-C rules even when headers or .m files overlap other
+     * registered language extensions.
+     */
+    readonly type = "objc";
+    /**
+     * Builds an owned Objective-C inventory from captured source contents.
+     *
+     * Unit publication precedes documentation materialization, and source or parser
+     * failures retain incomplete state. The runtime closes after accepted scans settle.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Reconciles public interfaces with compatible extension and implementation sites.
+     *
+     * The resulting map connects every retained physical declaration to its unit.
+     */
+    private materializeUnits;
+    /**
+     * Applies merged withdrawals before creating eligible annotation hosts.
+     *
+     * Hidden units cannot receive ordinary claim hosts after inheritance is resolved.
+     */
+    private materializeDocumentation;
+    /**
+     * Keeps every undocumented public declaration in the host denominator.
+     *
+     * Grouping by site prevents merged units from manufacturing duplicate hosts.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups carrier attachments by their physical declaration site.
+     *
+     * A host can therefore identify all published units attached at one source span.
+     */
+    private attachmentGroups;
+    /**
+     * Records supported ownership or an actionable unsupported carrier.
+     *
+     * Tagged comments without a supported owner remain visible to the graph reporter.
+     */
+    private host;
+    /**
+     * Parses mapped Doxygen after ownership and example masking are established.
+     *
+     * Tag parsing receives a host with its resolved unit IDs and original range.
+     */
+    private parse;
+    /**
+     * Recognizes annotations and withdrawals on otherwise unsupported carriers.
+     *
+     * Such carriers require a diagnostic instead of silently dropping author intent.
+     */
+    private annotation;
+    /**
+     * Detects graph annotations that cannot silently disappear on withdrawn units.
+     *
+     * Review and claim tags remain reportable even when their attached unit is hidden.
+     */
+    private claimAnnotation;
+    /**
+     * Finds tag boundaries in mapped comment text.
+     *
+     * Matching only line starts avoids treating prose or examples as annotations.
+     */
+    private annotationPattern;
+    /**
+     * Follows real parent identities when propagating withdrawals.
+     *
+     * The visited set prevents malformed ownership cycles from recursing indefinitely.
+     */
+    private withdrawn;
+    /**
+     * Keeps selector kinds and segmented nominal identities unambiguous.
+     *
+     * Symbol kind separates otherwise equal Objective-C name paths in the inventory.
+     */
+    private unitId;
+    /**
+     * Prevents an ambiguous declaration family from reporting complete analysis.
+     *
+     * The diagnostic preserves the selected source boundary and repair guidance.
+     */
+    private problem;
+}