@wrtnlabs/evidence 0.0.0

package/lib/adapters/ecmascript/IEcmaScriptCommentAttachment.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Connects a parsed JSDoc comment to one semantic declaration carrier.
+ *
+ * Comment materialization filters these records by public reachability and then
+ * uses their physical and semantic identities to create claims or withdrawals.
+ */
+export interface IEcmaScriptCommentAttachment {
+    /** Eligible host-position key when this carrier can make evidence claims.
+     *
+     * Omission marks a withdrawal-only attachment such as a constructor comment. */
+    positionId?: string;
+    /** Physical declaration site receiving the documentation.
+     *
+     * It remains separate from the unit so merged declarations retain attachment truth. */
+    siteId: string;
+    /** Semantic unit affected by this JSDoc carrier.
+     *
+     * Several units can share one physical host only when the scanner establishes it. */
+    unitId: string;
+    /** Limits the carrier to visibility withdrawal processing.
+     *
+     * Constructor documentation can hide parameter properties but cannot claim evidence. */
+    withdrawalOnly?: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptCommentAttachment.js

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

package/lib/adapters/ecmascript/IEcmaScriptExport.d.ts

@@ -0,0 +1,51 @@
+import type { EcmaScriptExportKind } from "./EcmaScriptExportKind";
+/**
+ * Describes one static export edge discovered in an ECMAScript-family module.
+ *
+ * The export resolver follows these edges through the source snapshot to expose
+ * local units under their public module names and diagnose unsupported targets.
+ */
+export interface IEcmaScriptExport {
+    /**
+     * Export form that determines how the resolver follows this edge.
+     *
+     * The kind distinguishes local declarations from named, namespace, and star
+     * re-exports, whose optional names and specifier have different meanings.
+     */
+    kind: EcmaScriptExportKind;
+    /**
+     * Name introduced by this module's public export surface.
+     *
+     * Omission is valid for star exports, which contribute each eligible public
+     * name from the referenced module except its default export.
+     */
+    publicName?: string;
+    /**
+     * Local binding name exported directly from this module.
+     *
+     * It is present for local export edges and lets the resolver distinguish a
+     * declared root from an imported binding that must be followed further.
+     */
+    localName?: string;
+    /**
+     * Name requested from the referenced module by a named re-export.
+     *
+     * Omission means this edge does not select one imported member, as with local,
+     * namespace, and star export forms.
+     */
+    importedName?: string;
+    /**
+     * Raw module specifier naming the re-export target.
+     *
+     * Omission means the exported binding is local; when present, resolution is
+     * limited to supported files inside the declared source snapshot.
+     */
+    specifier?: string;
+    /**
+     * Whether this edge exports only TypeScript type-space declarations.
+     *
+     * The resolver combines this flag with every edge it traverses so value-only
+     * units cannot appear through a type-only public address.
+     */
+    typeOnly: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptExport.js

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

package/lib/adapters/ecmascript/IEcmaScriptFileAnalysis.d.ts

@@ -0,0 +1,56 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { EcmaScriptModuleMode } from "./EcmaScriptModuleMode";
+import type { IEcmaScriptComment } from "./IEcmaScriptComment";
+import type { IEcmaScriptExport } from "./IEcmaScriptExport";
+import type { IEcmaScriptImport } from "./IEcmaScriptImport";
+import type { IEcmaScriptHostPosition } from "./IEcmaScriptHostPosition";
+import type { IEcmaScriptOwnedUnit } from "./IEcmaScriptOwnedUnit";
+/**
+ * Retains the node-free result of scanning one ECMAScript-family source file.
+ *
+ * The adapter combines these records after parsing ends to resolve exports,
+ * materialize documentation hosts, and preserve incomplete analysis as failure.
+ */
+export interface IEcmaScriptFileAnalysis {
+    /** Source snapshot that owns every extracted module record.
+     *
+     * Its physical path remains the basis for diagnostics and host locations. */
+    source: IEvidenceSourceFile;
+    /** Module semantics selected from syntax or JavaScript package scope.
+     *
+     * This governs which export and import forms the scanner may interpret. */
+    mode: EcmaScriptModuleMode;
+    /** Local semantic units before export reachability filters publication.
+     *
+     * Each entry preserves its root binding and type/value-space ownership. */
+    units: IEcmaScriptOwnedUnit[];
+    /** Local roots withdrawn by supported visibility documentation.
+     *
+     * Export resolution carries the withdrawal through re-export paths. */
+    excludedRoots: string[];
+    /** Static export edges used to calculate public reachability.
+     *
+     * The resolver evaluates the complete module graph before filtering units. */
+    exports: IEcmaScriptExport[];
+    /** Static imported bindings that local exports may forward.
+     *
+     * Dynamic loading is deliberately outside the declared-source boundary. */
+    imports: IEcmaScriptImport[];
+    /** Declaration positions eligible to become undocumented evidence hosts.
+     *
+     * They keep source ownership separate from semantic unit identity. */
+    positions: IEcmaScriptHostPosition[];
+    /** Parsed comments with scanner-established JSDoc attachments.
+     *
+     * A textually similar unattached block cannot claim evidence. */
+    comments: IEcmaScriptComment[];
+    /** Parse or unsupported-surface findings retained for the final inventory.
+     *
+     * Consumers must see these rather than receive a smaller passing population. */
+    diagnostics: IEvidenceDiagnostic[];
+    /** Whether scanning represented every relevant supported source construct.
+     *
+     * Completeness participates in the adapter's final failure state. */
+    complete: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptFileAnalysis.js

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

package/lib/adapters/ecmascript/IEcmaScriptHostPosition.d.ts

@@ -0,0 +1,25 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+/**
+ * Represents one physical declaration position eligible to host JSDoc evidence.
+ *
+ * The adapter emits the position as an undocumented host unless an attached,
+ * public comment replaces its range with a documented claim.
+ */
+export interface IEcmaScriptHostPosition {
+    /** Stable physical-position key used to deduplicate documented and empty hosts.
+     *
+     * It does not substitute for a semantic unit identity. */
+    id: string;
+    /** Declaration site associated with this host position.
+     *
+     * The site connects annotations to fingerprinted source ownership. */
+    siteId: string;
+    /** Exact range emitted for an undocumented eligible host.
+     *
+     * A documented comment replaces this position as the host's range. */
+    range: IEvidenceSourceRange;
+    /** Selected local units that legitimately share this declaration position.
+     *
+     * The adapter filters it by export reachability before publication. */
+    unitIds: string[];
+}

package/lib/adapters/ecmascript/IEcmaScriptHostPosition.js

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

package/lib/adapters/ecmascript/IEcmaScriptImport.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A static local binding imported from another ECMAScript module.
+ *
+ * The file scanner records only imports that an export may forward. Export
+ * resolution follows this record to the imported module instead of treating the
+ * local alias as a declaration owned by the importing source.
+ */
+export interface IEcmaScriptImport {
+    /**
+     * Local identifier introduced by the import declaration.
+     *
+     * A local export uses this name to find the imported binding in its module's
+     * import map.
+     */
+    localName: string;
+    /**
+     * Name requested from the imported module.
+     *
+     * Omission identifies a namespace import, whose local binding represents the
+     * entire target module rather than one exported name.
+     */
+    importedName?: string;
+    /**
+     * Authored module specifier naming the import target.
+     *
+     * The export resolver resolves this spelling relative to the importing source
+     * and reports unsupported package-resolution requests.
+     */
+    specifier: string;
+    /**
+     * Whether the binding is available only in TypeScript's type space.
+     *
+     * This includes a type-only import declaration or specifier and propagates to
+     * public addresses reached through a forwarded export.
+     */
+    typeOnly: boolean;
+    /**
+     * Whether the local name is a namespace binding.
+     *
+     * Namespace exports expand the target module's public names instead of
+     * resolving `importedName`.
+     */
+    namespace: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptImport.js

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

package/lib/adapters/ecmascript/IEcmaScriptModule.d.ts

@@ -0,0 +1,55 @@
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEcmaScriptExport } from "./IEcmaScriptExport";
+import type { IEcmaScriptImport } from "./IEcmaScriptImport";
+import type { IEcmaScriptOwnedUnit } from "./IEcmaScriptOwnedUnit";
+/**
+ * Resolver state retained for one parsed ECMAScript-family source module.
+ *
+ * `EcmaScriptExportResolver` converts scanner output into this mutable graph
+ * node, then uses it to follow local declarations, imports, and re-export edges
+ * while assigning public addresses to the inventory.
+ */
+export interface IEcmaScriptModule {
+    /**
+     * Captured source file represented by this graph node.
+     *
+     * Its identity selects the module in resolution, while its addresses provide
+     * the physical public files for each published unit.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Local units declared by this source before publication filtering.
+     *
+     * The resolver matches an export binding against each unit's root and appends
+     * its suffix after the public export path.
+     */
+    units: IEcmaScriptOwnedUnit[];
+    /**
+     * Local roots deliberately excluded from supported publication.
+     *
+     * An export of one of these roots propagates exclusion through re-exports
+     * without reporting that the module lacks a supported declaration.
+     */
+    excludedRoots: Set<string>;
+    /**
+     * Static export edges scanned from this module.
+     *
+     * Resolution chooses explicit edges before star edges for a requested public
+     * name and follows their local or module-qualified targets.
+     */
+    exports: IEcmaScriptExport[];
+    /**
+     * Imported bindings keyed by their local identifier.
+     *
+     * A local export consults this map to distinguish an imported alias from a
+     * declaration owned by this module.
+     */
+    imports: Map<string, IEcmaScriptImport>;
+    /**
+     * Public names currently known for this module.
+     *
+     * The resolver seeds this set from explicit exports and expands it with names
+     * reachable through star exports before publishing addresses.
+     */
+    names: Set<string>;
+}

package/lib/adapters/ecmascript/IEcmaScriptModule.js

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

package/lib/adapters/ecmascript/IEcmaScriptModuleResolution.d.ts

@@ -0,0 +1,40 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceDependency } from "../../structures/IEvidenceSourceDependency";
+import type { EcmaScriptModuleMode } from "./EcmaScriptModuleMode";
+/**
+ * Module-mode selection and its evidence for an ECMAScript source snapshot.
+ *
+ * The adapter consumes this result before parsing files so scanner behavior uses
+ * the selected ESM or CommonJS semantics and inventory completeness preserves
+ * any package-metadata failure.
+ */
+export interface IEcmaScriptModuleResolution {
+    /**
+     * Module semantics selected for each captured source ID.
+     *
+     * Each source must select one mode across all of its logical addresses before
+     * the scanner interprets its import and export syntax.
+     */
+    modes: Map<string, EcmaScriptModuleMode>;
+    /**
+     * Package metadata paths whose changes can alter mode selection.
+     *
+     * The watcher retains these exact dependencies, including missing manifests,
+     * so creating or repairing package metadata triggers reevaluation.
+     */
+    dependencies: IEvidenceSourceDependency[];
+    /**
+     * Failures encountered while reading or interpreting package metadata.
+     *
+     * The adapter adds these findings to the inventory instead of continuing with
+     * an apparently successful result built from incomplete mode information.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Whether mode selection completed without diagnostics.
+     *
+     * False prevents the final inventory from proving coverage while still
+     * retaining the fallback modes and actionable failures.
+     */
+    complete: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptModuleResolution.js

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

package/lib/adapters/ecmascript/IEcmaScriptOwnedUnit.d.ts

@@ -0,0 +1,45 @@
+import type { IEvidenceUnit } from "../../structures/IEvidenceUnit";
+/**
+ * A local evidence unit together with the binding path that owns it.
+ *
+ * The scanner creates this record before export resolution. The resolver uses
+ * the root to match a local binding and the suffix to extend its public address
+ * for nested declarations such as class members or namespace contents.
+ */
+export interface IEcmaScriptOwnedUnit {
+    /**
+     * Semantic declaration extracted into the evidence inventory.
+     *
+     * This identity remains one unit even when several public export paths expose
+     * it through aliases or re-exports.
+     */
+    unit: IEvidenceUnit;
+    /**
+     * Outermost local binding through which this unit is owned.
+     *
+     * Export resolution compares a resolved local name with this root before
+     * publishing the unit and its nested suffix.
+     */
+    root: string;
+    /**
+     * Segments below `root` in a public address.
+     *
+     * A root declaration has no suffix; members and nested namespace declarations
+     * append their literal segments after the export name.
+     */
+    suffix: string[];
+    /**
+     * Whether this declaration exists in the TypeScript type space.
+     *
+     * A type-only export may publish this unit, while value-only units remain
+     * unavailable through that path.
+     */
+    typeSpace: boolean;
+    /**
+     * Whether this declaration exists in the JavaScript value space.
+     *
+     * Merged declarations can occupy both spaces, and ordinary value exports
+     * publish units regardless of this flag's counterpart.
+     */
+    valueSpace: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptOwnedUnit.js

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

package/lib/adapters/ecmascript/IEcmaScriptResolution.d.ts

@@ -0,0 +1,31 @@
+import type { IEcmaScriptBinding } from "./IEcmaScriptBinding";
+/**
+ * Result of following one exported name through the static module graph.
+ *
+ * The export resolver caches this result for each source and name, then uses its
+ * bindings to publish units and its state flags to distinguish exclusions and
+ * declaration-free cycles from missing supported declarations.
+ */
+export interface IEcmaScriptResolution {
+    /**
+     * Local declarations or namespace modules reached by the exported name.
+     *
+     * Multiple bindings can result from star exports; each carries the source and
+     * type-space restriction needed during publication.
+     */
+    bindings: IEcmaScriptBinding[];
+    /**
+     * Whether any resolution path reaches a deliberately excluded root.
+     *
+     * Exclusion suppresses a missing-declaration diagnostic and propagates through
+     * local and re-export paths.
+     */
+    excluded: boolean;
+    /**
+     * Whether traversal encountered the same source-and-name pair recursively.
+     *
+     * A result with no bindings and this flag identifies a declaration-free export
+     * cycle that must be reported instead of silently publishing nothing.
+     */
+    cyclic: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptResolution.js

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

package/lib/adapters/ecmascript/IEcmaScriptStatementContext.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Declaration state inherited while the scanner walks a statement list.
+ *
+ * Namespace recursion extends this context so nested units preserve semantic
+ * ownership and public address paths while declaration modifiers continue to
+ * govern their visibility and type-space eligibility.
+ */
+export interface IEcmaScriptStatementContext {
+    /**
+     * Literal semantic identity segments inherited from enclosing namespaces.
+     *
+     * Each discovered declaration appends its own name to form the unit identity
+     * and structural ownership chain.
+     */
+    semanticPrefix: string[];
+    /**
+     * Public-address segments inherited below the root binding.
+     *
+     * Nested declarations append their names here so published addresses retain
+     * namespace and member structure after the root export name.
+     */
+    publicPrefix: string[];
+    /**
+     * Outermost local binding that owns nested declarations.
+     *
+     * Omission at file scope makes each declaration its own root; namespace scans
+     * set it so their contents publish through the enclosing binding.
+     */
+    root?: string;
+    /**
+     * Evidence unit ID of the direct enclosing declaration.
+     *
+     * Omission denotes a root unit. Nested scanner calls pass this ID so inventory
+     * structure follows language containment instead of public path spelling.
+     */
+    parentId?: string;
+    /**
+     * Whether enclosing syntax declares an ambient TypeScript context.
+     *
+     * Ambient declarations are treated as exportable while visibility is being
+     * calculated because their module contract is declared rather than executed.
+     */
+    ambient: boolean;
+    /**
+     * Whether declarations in this context can produce supported units.
+     *
+     * Nested declarations require their enclosing namespace to be visible and to
+     * use an export modifier; file-scope declarations begin visible.
+     */
+    visible: boolean;
+    /**
+     * Whether enclosing export syntax restricts declarations to the type space.
+     *
+     * Functions and variables stop scanning under this flag, while TypeScript type
+     * declarations retain the restriction for later export resolution.
+     */
+    typeOnly: boolean;
+}

package/lib/adapters/ecmascript/IEcmaScriptStatementContext.js

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

package/lib/adapters/ecmascript/IJavaScriptPackageJson.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package metadata consulted when JavaScript files lack an explicit mode extension.
+ *
+ * `EcmaScriptModuleResolver` parses the nearest `package.json` and uses this
+ * narrow contract to select CommonJS or ESM semantics for ordinary JavaScript
+ * source files.
+ */
+export interface IJavaScriptPackageJson {
+    /**
+     * Package-wide JavaScript module interpretation requested by the author.
+     *
+     * Omission and `"commonjs"` select CommonJS, `"module"` selects ESM, and any
+     * other value produces a diagnostic before the resolver falls back to CommonJS.
+     */
+    type?: string;
+}

package/lib/adapters/ecmascript/IJavaScriptPackageJson.js

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

package/lib/adapters/go/EvidenceGoAdapter.d.ts

@@ -0,0 +1,15 @@
+import { GoAdapter } from "./GoAdapter";
+/**
+ * Extracts exported Go declarations with package-wide receiver ownership.
+ *
+ * Selected files are scanned before package resolution attaches receiver methods
+ * and interface members to their owner types. Package and test-file boundaries
+ * remain explicit; a documentation comment can participate only at an eligible
+ * declaration position. Public paths stay file-qualified after reconciliation.
+ *
+ * Analysis does not evaluate GOOS, GOARCH, promoted members, or dependency-derived
+ * declarations. Conditional or unresolved public ownership must not produce a
+ * passing inventory with the affected declarations missing.
+ */
+export declare class EvidenceGoAdapter extends GoAdapter {
+}

package/lib/adapters/go/EvidenceGoAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceGoAdapter = void 0;
+const GoAdapter_1 = require("./GoAdapter");
+/**
+ * Extracts exported Go declarations with package-wide receiver ownership.
+ *
+ * Selected files are scanned before package resolution attaches receiver methods
+ * and interface members to their owner types. Package and test-file boundaries
+ * remain explicit; a documentation comment can participate only at an eligible
+ * declaration position. Public paths stay file-qualified after reconciliation.
+ *
+ * Analysis does not evaluate GOOS, GOARCH, promoted members, or dependency-derived
+ * declarations. Conditional or unresolved public ownership must not produce a
+ * passing inventory with the affected declarations missing.
+ */
+class EvidenceGoAdapter extends GoAdapter_1.GoAdapter {
+}
+exports.EvidenceGoAdapter = EvidenceGoAdapter;

package/lib/adapters/go/GoAdapter.d.ts

@@ -0,0 +1,43 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Coordinates Go file scanning, package ownership, and documentation materialization.
+ *
+ * A file scan cannot resolve every method owner: receiver types can live in
+ * another selected file of the package. `GoPackageResolver` therefore publishes
+ * identities and addresses after all file analyses exist. Documentation then
+ * joins those identities through recorded declaration sites, including grouped
+ * declarations and package-specific test boundaries.
+ *
+ * The pipeline retains discovery and parse failures before common inventory
+ * validation. It never treats an unresolved receiver as permission to omit a
+ * method and report complete coverage over the remaining units.
+ */
+export declare class GoAdapter implements IEvidenceAdapter {
+    /**
+     * Go artifact discriminator for the package extraction pipeline.
+     *
+     * This selects Go visibility and receiver rules. Package placement comes from
+     * the selected source records rather than from claim or reference role.
+     */
+    readonly type = "go";
+    /**
+     * Builds a Go package inventory from an independently captured input snapshot.
+     *
+     * All files are scanned before package publication and documentation attachment.
+     * Discovery dependencies survive for watch recovery, and the invocation closes
+     * its parser on every path before returning a serializable inventory.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    private materializeDocumentation;
+    private materializeUndocumentedHosts;
+    private attachmentGroups;
+    private host;
+    private parse;
+    private annotation;
+    private claimAnnotation;
+    private annotationPattern;
+    private withdrawn;
+}