@wrtnlabs/evidence 0.0.0

package/lib/adapters/php/IPhpDeclaration.d.ts

@@ -0,0 +1,64 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Captures one PHP declaration before public inventory materialization.
+ *
+ * PhpAdapter groups these lexical records into semantic units, retaining exact
+ * source spelling for public addresses while separately normalizing identity.
+ */
+export interface IPhpDeclaration {
+    /**
+     * Stable scanner identity for this declaration occurrence.
+     *
+     * Documentation attachments and owner links use it before public units exist.
+     */
+    id: string;
+    /**
+     * Declaration name exactly as PHP source spells it.
+     *
+     * Property names retain `$`, which is meaningful to public target construction.
+     */
+    name: string;
+    /**
+     * Evidence selector family assigned to this declaration.
+     *
+     * Consumers use it to distinguish nominal types, functions, and properties.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Tree-sitter declaration form that established this record.
+     *
+     * It lets later validation distinguish source constructs sharing one selector category.
+     */
+    form: string;
+    /**
+     * Namespace and lexical-owner segments forming semantic identity.
+     *
+     * PhpAdapter applies PHP case rules to this path without changing public spelling.
+     */
+    identity: string[];
+    /**
+     * Exact accessor segments published beneath this declaration's source file.
+     *
+     * Address aliases remain independent of semantic identity and preserve case-sensitive properties.
+     */
+    address: string[];
+    /**
+     * Source site and content ranges used for fingerprints and documentation hosts.
+     *
+     * The scanner can include declaration carriers and separated property elements precisely.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Whether lexical PHP visibility exposes this declaration on the supported surface.
+     *
+     * A hidden owner also prevents all of its members from being published.
+     */
+    public: boolean;
+    /**
+     * Scanner identity of the enclosing nominal declaration when this is a member.
+     *
+     * Omission denotes a namespace-level declaration with no inherited visibility boundary.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/php/IPhpDeclaration.js

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

package/lib/adapters/php/IPhpDocumentation.d.ts

@@ -0,0 +1,35 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IPhpDocumentationAttachment } from "./IPhpDocumentationAttachment";
+/**
+ * Retains one PHPDoc carrier, including a carrier whose placement is unsupported.
+ *
+ * The adapter preserves unsupported tagged text as a diagnostic host so directives
+ * cannot disappear merely because no eligible declaration receives the comment.
+ */
+export interface IPhpDocumentation {
+    /**
+     * Stable scanner identity for this documentation region.
+     *
+     * It distinguishes host records even when nearby declarations share a site.
+     */
+    id: string;
+    /**
+     * Original UTF-16 range occupied by the PHPDoc comment.
+     *
+     * Annotation ranges exclude it from declaration review fingerprints.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Delimiter and tag-boundary rules used to map the carrier's text.
+     *
+     * PhpDocumentation also uses this classification to mask examples without moving offsets.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Declaration sites to which this carrier is immediately attached.
+     *
+     * A comment can serve multiple units at one site before withdrawal hides descendants.
+     */
+    attachments: IPhpDocumentationAttachment[];
+}

package/lib/adapters/php/IPhpDocumentation.js

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

package/lib/adapters/php/IPhpDocumentationAttachment.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Links a PHPDoc carrier to one declaration at an adjacent source site.
+ *
+ * PhpAdapter resolves this scanner-local relationship only after it has created
+ * public units, allowing unsupported or private attachment to remain visible.
+ */
+export interface IPhpDocumentationAttachment {
+    /**
+     * Scanner identity of the declaration receiving this documentation.
+     *
+     * The adapter maps it to a materialized unit before tags can affect withdrawals.
+     */
+    declarationId: string;
+    /**
+     * Shared source-site identity for the attached declaration.
+     *
+     * It groups accessors that must produce one documentation host.
+     */
+    siteId: string;
+}

package/lib/adapters/php/IPhpDocumentationAttachment.js

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

package/lib/adapters/php/IPhpFileAnalysis.d.ts

@@ -0,0 +1,48 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IPhpDeclaration } from "./IPhpDeclaration";
+import type { IPhpDocumentation } from "./IPhpDocumentation";
+/**
+ * Preserves one PHP file's serializable extraction after parsing.
+ *
+ * PhpAdapter materializes its units only after all selected files have yielded
+ * declarations, diagnostics, documentation carriers, and context for digests.
+ */
+export interface IPhpFileAnalysis {
+    /**
+     * Selected source snapshot represented by this analysis.
+     *
+     * Its path anchors declaration identities and diagnostic locations.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lexical declarations awaiting visibility and duplicate reconciliation.
+     *
+     * Only public, conflict-free entries become inventory units and addresses.
+     */
+    declarations: IPhpDeclaration[];
+    /**
+     * PHPDoc carriers with their immediate declaration attachments.
+     *
+     * Tagged unsupported carriers remain available for diagnostic host creation.
+     */
+    documentation: IPhpDocumentation[];
+    /**
+     * Source or classification failures discovered for this file.
+     *
+     * These prevent a partial public surface from being considered complete.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * File-local imports and directives that affect declaration meaning.
+     *
+     * Complete inventories fold normalized entries into review content digests.
+     */
+    context: string[];
+    /**
+     * Whether every surface-changing construct in this file was classified.
+     *
+     * The adapter propagates false to reject coverage based on an incomplete population.
+     */
+    complete: boolean;
+}

package/lib/adapters/php/IPhpFileAnalysis.js

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

package/lib/adapters/php/PhpAdapter.d.ts

@@ -0,0 +1,108 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Extracts PHP public identities and documentation with file-context fingerprints.
+ *
+ * Declaration groups and public addresses are materialized before annotations.
+ * Local imports and directives can change declaration meaning without changing
+ * its own source span, so complete inventories incorporate that context into
+ * content digests after normalization.
+ */
+export declare class PhpAdapter implements IEvidenceAdapter {
+    /**
+     * Artifact family selecting PHP parsing and source-public extraction.
+     *
+     * The value connects population configuration to this adapter's visibility and
+     * documentation attachment rules.
+     */
+    readonly type = "php";
+    /**
+     * Builds a serializable PHP inventory while retaining source and parser failures.
+     *
+     * Input is validated and cloned before scanning. Only a complete normalized
+     * inventory receives context-sensitive digests, and parser resources close in cleanup.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    /**
+     * Incorporates local imports and directives into declaration review content.
+     *
+     * Context is combined with the existing content digest without widening physical
+     * declaration ranges. All new digests are computed before assignment so iteration
+     * order cannot make later calculations observe partially updated units.
+     */
+    private contextDigests;
+    private scan;
+    /**
+     * Materializes public PHP identities and reports conflicting declarations.
+     *
+     * It retains compatible physical sites under one unit while emitting each configured file address.
+     */
+    private materializeUnits;
+    /**
+     * Attaches PHPDoc after unit materialization and reconciles withdrawals.
+     *
+     * Unsupported tagged carriers still receive diagnostic hosts so their directives remain visible.
+     */
+    private materializeDocumentation;
+    /**
+     * Creates hosts for public declarations without attached documentation.
+     *
+     * This preserves their claim obligations after withdrawn and documented units are excluded.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups a PHPDoc carrier's published declarations by physical source site.
+     *
+     * One carrier can attach to multiple units, but each site requires its own host boundary.
+     */
+    private attachmentGroups;
+    /**
+     * Creates a host for attached documentation or an unsupported tagged carrier.
+     *
+     * The host retains the original source range and eligible unit IDs for tag parsing.
+     */
+    private host;
+    /**
+     * Parses evidence tags after the adapter has established their owning host.
+     *
+     * This prevents source-adjacent text from acquiring units through later lexical coincidence.
+     */
+    private parse;
+    /**
+     * Detects supported annotations on a PHPDoc carrier before it has a host.
+     *
+     * The result decides whether unsupported placement requires an actionable diagnostic host.
+     */
+    private annotation;
+    /**
+     * Distinguishes claim annotations from withdrawal-only documentation.
+     *
+     * Withdrawn units suppress ordinary hosts unless the carrier still contains an independent claim.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported tag names at normalized documentation line boundaries.
+     *
+     * Parsing uses PHPDoc masking first so examples cannot accidentally create declarations.
+     */
+    private annotationPattern;
+    /**
+     * Determines whether a unit is withdrawn directly or through its lexical parent.
+     *
+     * The visited set prevents malformed ownership cycles from making withdrawal traversal recurse indefinitely.
+     */
+    private withdrawn;
+    /**
+     * Builds the unit ID using PHP's case-insensitive identity rules where applicable.
+     *
+     * Public accessor spelling remains separate so case-sensitive properties retain their address.
+     */
+    private unitId;
+    /**
+     * Records a declaration conflict and marks the inventory incomplete.
+     *
+     * This prevents duplicate public identities from reducing the population to a passing subset.
+     */
+    private problem;
+}