@haystackeditor/cli 0.24.1 → 0.25.0

package/dist/commands/telemetry.d.ts

@@ -1,5 +1,7 @@
+import { type SettingLiteral, type TelemetrySettingsEntryV1, type TelemetrySettingsProposal } from './server-telemetry-contract.js';
+import { type TypeImportResolver } from '../telemetry/typed-source.js';
 export declare function preloadBabel(): Promise<void>;
-declare const MANIFEST_SCHEMA_VERSION = "haystack-node-telemetry-instrumentation-v3";
+declare const MANIFEST_SCHEMA_VERSION = "haystack-node-telemetry-instrumentation-v4";
 export interface TelemetryInstrumentOptions {
     entry: string;
     sourceRoot?: string;
@@ -24,6 +26,31 @@ export interface InstrumentedFileSummary {
         returns: number;
         throws: number;
     };
+    /** Rule 9(b)/(c): the file's typed source was read (declared fields, literal domains); false: shape-only. */
+    typed: boolean;
+}
+/** Rule 9(c): what the build did with `.haystack/telemetry-settings.json`. */
+export interface TelemetrySettingsReport {
+    /** The settings file read, repository-relative, or null when the repository has none. */
+    file: string | null;
+    /** Why the file (or an entry) was not used; the build still ships. */
+    problems: string[];
+    /** Sites that record literals: the approved literals their typed source still declares. */
+    applied: Array<{
+        source_path: string;
+        qualified_name: string;
+        label: string;
+        literals: SettingLiteral[];
+    }>;
+    /** Approved entries the instrumenter refused (identity- or secret-looking, or no longer a literal domain). */
+    refused: Array<{
+        source_path: string;
+        qualified_name: string;
+        label: string;
+        why: string;
+    }>;
+    /** Approved entries no instrumented site of this build matches. */
+    unmatched: TelemetrySettingsEntryV1[];
 }
 export interface TelemetryInstrumentationResult {
     schema_version: typeof MANIFEST_SCHEMA_VERSION;
@@ -34,6 +61,12 @@ export interface TelemetryInstrumentationResult {
     instrumented_files: InstrumentedFileSummary[];
     sites: InstrumentedSite[];
     skipped_unmapped_files: string[];
+    /** Rule 13(b): compiled files the instrumenter could not transform, shipped exactly as built. */
+    skipped_untransformed_files: Array<{
+        output_path: string;
+        reason: string;
+    }>;
+    settings: TelemetrySettingsReport;
     already_instrumented: boolean;
 }
 export interface InstrumentedSite {
@@ -45,7 +78,10 @@ export interface InstrumentedSite {
     owner_key: string;
     structural_key: string;
     label?: string;
+    /** Rule 9(b): source-declared field names (read on the value, or declared by its type), at most SERVER_FIELDS_PER_SITE. */
     allowed_fields: string[];
+    /** Rule 9(c): an approved settings site's literals (approved and still declared by the typed source). */
+    settings?: SettingLiteral[];
     /**
      * 1-based line and 0-based column of the probed node in `source_path`.
      * Present only when the instrumented text IS the source (the bundler
@@ -63,6 +99,22 @@ export interface FileProbeCounts {
     returns: number;
     throws: number;
 }
+/** What the typed source declares at one site; `fields` in declaration order. */
+interface SiteTypeFacts {
+    fields: string[];
+    domain: SettingLiteral[] | null;
+    typeNames: string[];
+}
+type TypedSiteFacts = Map<string, SiteTypeFacts | {
+    ambiguous: true;
+}>;
+/**
+ * Rule 9(b)/(c): per site of a TYPED source file (keyed by the site's function and label exactly as instrumentSource
+ * names them), the fields its type declares and its literal domain. Compiled output loses the types, so the compiled-
+ * output path reads the original TypeScript beside it and joins by this key; the bundler path reads the module it
+ * instruments. A key the file declares twice with different facts is ambiguous and keeps neither.
+ */
+export declare function collectTypedSiteFacts(code: string, parserPlugins: string[], resolve: TypeImportResolver | null): TypedSiteFacts;
 /**
  * The runtime source bound to one control channel, plus the integrity token
  * generated probes present to it and the hash a bootstrap verifies before
@@ -75,19 +127,45 @@ export declare function authenticateTelemetryRuntime(controlChannel: string): {
     integrity: string;
     hash: string;
 };
+/** The repository root settings and repository-relative paths are read against: git's top level, else `start`. */
+export declare function repositoryRoot(start: string): string;
+/** Rule 9(c): the repository's reviewed settings allowlist, the only file instrumentation treats as approval (a
+ * proposal never is). A missing file is no settings; an unreadable file or entry is a problem the build reports,
+ * never a reason to fail it. */
+export declare function readTelemetrySettings(repoRoot: string): {
+    file: string | null;
+    entries: TelemetrySettingsEntryV1[];
+    problems: string[];
+};
+/** Relative imports one hop away, parsed once per build: `./types`, `./types.js` (NodeNext) and `./types/index`. */
+export declare function typeImportResolver(repoRoot: string): (fromFile: string) => TypeImportResolver;
 export declare function instrumentNodeTelemetryBuild(distDirectory: string, options: TelemetryInstrumentOptions): TelemetryInstrumentationResult;
+/** The build output could not be put back exactly as it was; the files named are left instrumented, without a
+ * manifest, so the runtime installs nothing and every probe passes values through. */
+export declare class PartialRestoreError extends Error {
+}
 export declare const BUNDLED_SOURCE_EXTENSIONS: string[];
+/** What one bundled module did with the settings allowlist (merged by the post-compile step). */
+export interface BundledSettingsRecord {
+    applied: TelemetrySettingsReport['applied'];
+    refused: TelemetrySettingsReport['refused'];
+    /** Approved entries this module's sites matched, as `sourcePath\0qualifiedName\0label`. */
+    matched: string[];
+}
 export type BundledModuleResult = {
     kind: 'instrumented';
     code: string;
+    map: Record<string, unknown> | null;
     probes: FileProbeCounts;
     sites: InstrumentedSite[];
+    typed: boolean;
+    settings: BundledSettingsRecord;
 }
-/** Already instrumented, or a "use client" module (its server copy is only the SSR render of browser code). */
+/** Already instrumented, a "use client" module, or an edge-runtime module. */
  | {
     kind: 'unchanged';
 }
-/** Babel cannot parse it (syntax the bundler's own compiler accepts but Babel does not). */
+/** Babel cannot parse it (syntax the bundler's own compiler accepts but Babel does not), or the transform failed. */
  | {
     kind: 'unparsed';
     reason: string;
@@ -95,15 +173,19 @@ export type BundledModuleResult = {
 /**
  * Instrument one source module inside a bundler. `sourcePath` is the
  * repository-relative path every site records, so production counts join the
- * change's files and line ranges exactly. A module Babel cannot parse is
- * reported, not thrown: the bundler's compiler may accept syntax Babel does
- * not, and telemetry must never be the reason a build fails. Any other error
- * is ours and stays loud.
+ * change's files and line ranges exactly. Rule 13(b): nothing here fails a
+ * build: a module Babel cannot parse or this pass cannot transform is reported
+ * and ships as written, with its input map.
  */
 export declare function instrumentBundledModule(code: string, options: {
     sourcePath: string;
+    /** The module's absolute path (its source map's file, and where relative type imports resolve from). */
+    absolutePath: string;
+    /** The repository root: where `.haystack/telemetry-settings.json` is read. */
+    sourceRoot: string;
     controlChannel: string;
     runtimeIntegrity: string;
+    inputSourceMap: object | null;
 }): BundledModuleResult;
 export interface BundledTelemetryManifest {
     schema_version: typeof MANIFEST_SCHEMA_VERSION;
@@ -116,14 +198,48 @@ export interface BundledTelemetryManifest {
     instrumented_files: Array<{
         source_path: string;
         probes: FileProbeCounts;
+        typed: boolean;
     }>;
-    /** Server modules shipped uninstrumented because Babel could not parse them, with the parser's reason. */
+    /** Server modules shipped uninstrumented because Babel could not parse or this pass could not transform them. */
     skipped_unparsed_files: Array<{
         source_path: string;
         reason: string;
     }>;
+    /** How site paths were named: from the git checkout (repository-relative, tracked files only), or, in a build without
+     * git, relative to the project with what that loses said. */
+    source_identity: BundledSourceIdentity;
+    settings: TelemetrySettingsReport;
     sites: InstrumentedSite[];
 }
+export interface BundledSourceIdentity {
+    git: boolean;
+    lost: string | null;
+}
+/** Rule 13(b): what a build that could not be instrumented leaves behind: the reason, and a preload that does nothing,
+ * so a server started with NODE_OPTIONS=--require=<it> starts exactly as it would without telemetry. */
+export interface BundledTelemetryNotInstalled {
+    schema_version: typeof MANIFEST_SCHEMA_VERSION;
+    bundler: string;
+    installed: false;
+    reason: string;
+    skipped_unparsed_files: Array<{
+        source_path: string;
+        reason: string;
+    }>;
+    sites: [];
+}
+export declare function writeInertTelemetryRuntime(options: {
+    outputDirectory: string;
+    bundler: string;
+    reason: string;
+    unparsed?: Array<{
+        sourcePath: string;
+        reason: string;
+    }>;
+}): {
+    registerPath: string;
+    report: BundledTelemetryNotInstalled;
+};
 /**
  * Write the runtime, its manifest and the preload that installs it into
  * `<outputDirectory>/.haystack-telemetry/`. The runtime reads the manifest
@@ -135,10 +251,13 @@ export declare function writeBundledTelemetryRuntime(options: {
     controlChannel: string;
     bundler: string;
     sourceRoot: string;
+    sourceIdentity: BundledSourceIdentity;
     modules: Array<{
         sourcePath: string;
         probes: FileProbeCounts;
         sites: InstrumentedSite[];
+        typed: boolean;
+        settings: BundledSettingsRecord;
     }>;
     unparsed: Array<{
         sourcePath: string;
@@ -148,7 +267,41 @@ export declare function writeBundledTelemetryRuntime(options: {
     registerPath: string;
     manifest: BundledTelemetryManifest;
 };
+/** The settings and typed-source lines a build prints (rule 8e: init's status repeats them). */
+export declare function settingsSummary(report: TelemetrySettingsReport, typedFiles: number, totalFiles: number): string[];
 export declare function telemetryInstrumentCommand(distDirectory: string, options: TelemetryInstrumentOptions & {
     includeSymbolsFile?: string;
 }): Promise<void>;
+/**
+ * Rule 9(c): propose settings. Every parameter and binding of the repository's typed source whose type is a closed set
+ * of literals (a union, a boolean, an enum, an `as const` array or object) is a candidate, refused when its name or a
+ * literal looks like identity or a secret. The proposal (SETTINGS_PROPOSAL_PATH) is the approved entries, unchanged,
+ * plus the new candidates; it approves nothing: only `haystack telemetry settings --approve`, run by a person, makes it
+ * the allowlist instrumentation reads.
+ */
+export declare function proposeTelemetrySettings(repoRoot: string): TelemetrySettingsProposal;
+/** What promoting the proposal would change in the approved allowlist, entry by entry. */
+export declare function settingsApprovalDiff(repoRoot: string): {
+    proposal: {
+        file: string | null;
+        entries: TelemetrySettingsEntryV1[];
+        problems: string[];
+    };
+    added: TelemetrySettingsEntryV1[];
+    removed: TelemetrySettingsEntryV1[];
+    changed: Array<{
+        from: TelemetrySettingsEntryV1;
+        to: TelemetrySettingsEntryV1;
+    }>;
+    refused: Array<{
+        entry: TelemetrySettingsEntryV1;
+        why: string;
+    }>;
+};
+export declare function telemetrySettingsCommand(options: {
+    propose?: boolean;
+    approve?: boolean;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<void>;
 export {};