@forge-ts/core 0.8.0 → 0.14.0

package/dist/index.d.ts

@@ -1,3 +1,253 @@
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+
+/**
+ * Append-only audit trail for forge-ts configuration and governance events.
+ *
+ * Events are stored as JSON Lines in `.forge-audit.jsonl` at the project root.
+ * Each line is a single JSON object — the file is never truncated or overwritten.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Discriminated event types recorded in the audit trail.
+ *
+ * @public
+ */
+type AuditEventType = "config.lock" | "config.unlock" | "config.drift" | "bypass.create" | "bypass.expire" | "rule.change";
+/**
+ * A single audit event recorded in the forge-ts audit trail.
+ *
+ * @public
+ */
+interface AuditEvent {
+    /** ISO 8601 timestamp of when the event occurred. */
+    timestamp: string;
+    /** Discriminated event type. */
+    event: AuditEventType;
+    /** OS username of the actor (falls back to "unknown"). */
+    user: string;
+    /** Mandatory for lock/unlock/bypass events; optional otherwise. */
+    reason?: string;
+    /** Event-specific payload. */
+    details: Record<string, unknown>;
+}
+/**
+ * Returns the current OS username, or "unknown" if unavailable.
+ *
+ * @returns The OS username string.
+ * @example
+ * ```typescript
+ * import { getCurrentUser } from "@forge-ts/core/audit";
+ * const user = getCurrentUser(); // e.g. "alice"
+ * ```
+ * @internal
+ */
+declare function getCurrentUser(): string;
+/**
+ * Appends a single audit event to the `.forge-audit.jsonl` file.
+ *
+ * Creates the file if it does not exist. The file is strictly append-only —
+ * existing content is never modified or truncated.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @param event - The audit event to record.
+ * @example
+ * ```typescript
+ * import { appendAuditEvent } from "@forge-ts/core";
+ * appendAuditEvent("/path/to/project", {
+ *   timestamp: new Date().toISOString(),
+ *   event: "config.lock",
+ *   user: "alice",
+ *   reason: "Stabilize v2 config",
+ *   details: { hash: "abc123" },
+ * });
+ * ```
+ * @public
+ */
+declare function appendAuditEvent(rootDir: string, event: AuditEvent): void;
+/**
+ * Options for reading the audit log.
+ *
+ * @public
+ */
+interface ReadAuditOptions {
+    /** Maximum number of events to return. */
+    limit?: number;
+    /** Filter to a single event type. */
+    eventType?: AuditEventType;
+}
+/**
+ * Reads the `.forge-audit.jsonl` file and returns parsed audit events.
+ *
+ * Returns newest events first. If the file does not exist, returns an empty
+ * array.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @param options - Optional limit and event type filter.
+ * @returns Array of audit events, newest first.
+ * @example
+ * ```typescript
+ * import { readAuditLog } from "@forge-ts/core";
+ * const events = readAuditLog("/path/to/project", { limit: 10 });
+ * console.log(events.length); // up to 10
+ * ```
+ * @public
+ */
+declare function readAuditLog(rootDir: string, options?: ReadAuditOptions): AuditEvent[];
+/**
+ * Formats a single audit event as a human-readable string.
+ *
+ * @param event - The audit event to format.
+ * @returns A single-line human-readable representation.
+ * @example
+ * ```typescript
+ * import { formatAuditEvent } from "@forge-ts/core";
+ * const line = formatAuditEvent({
+ *   timestamp: "2026-03-21T12:00:00.000Z",
+ *   event: "config.lock",
+ *   user: "alice",
+ *   reason: "Stabilize v2 config",
+ *   details: { hash: "abc123" },
+ * });
+ * console.log(line);
+ * // "[2026-03-21T12:00:00.000Z] config.lock by alice — Stabilize v2 config  {hash: abc123}"
+ * ```
+ * @public
+ */
+declare function formatAuditEvent(event: AuditEvent): string;
+
+/**
+ * Bypass budget system for forge-ts config governance.
+ *
+ * Allows agents to temporarily bypass locked rules with a limited daily budget.
+ * Each bypass requires a mandatory justification and expires after a configurable
+ * duration. All bypass events are recorded in the audit trail.
+ *
+ * Bypass records are stored in `.forge-bypass.json` at the project root as a
+ * JSON array of {@link BypassRecord} objects.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Configuration for the bypass budget system.
+ *
+ * @public
+ */
+interface BypassConfig {
+    /** Maximum number of bypasses allowed per calendar day. Default: 3 */
+    dailyBudget: number;
+    /** Duration in hours before a bypass automatically expires. Default: 24 */
+    durationHours: number;
+}
+/**
+ * A single bypass record stored in `.forge-bypass.json`.
+ *
+ * @public
+ */
+interface BypassRecord {
+    /** Unique identifier for this bypass. */
+    id: string;
+    /** ISO 8601 timestamp when the bypass was created. */
+    createdAt: string;
+    /** ISO 8601 timestamp when the bypass expires. */
+    expiresAt: string;
+    /** Mandatory justification for why the bypass was created. */
+    reason: string;
+    /** Specific rule code bypassed (e.g., "E009"), or "all" for a blanket bypass. */
+    rule: string;
+    /** OS username of the actor who created the bypass. */
+    user: string;
+}
+/**
+ * Creates a new bypass record, writes it to `.forge-bypass.json`, and appends
+ * an audit event.
+ *
+ * Throws an error if the daily budget is exhausted.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @param reason - Mandatory justification for the bypass.
+ * @param rule - Specific rule code to bypass (e.g., "E009"), or "all". Defaults to "all".
+ * @param config - Optional bypass budget configuration overrides.
+ * @returns The created bypass record.
+ * @throws Error when the daily bypass budget is exhausted.
+ * @example
+ * ```typescript
+ * import { createBypass } from "@forge-ts/core";
+ * const bypass = createBypass("/path/to/project", "hotfix for release", "E009");
+ * console.log(bypass.id); // unique bypass ID
+ * ```
+ * @public
+ */
+declare function createBypass(rootDir: string, reason: string, rule?: string, config?: Partial<BypassConfig>): BypassRecord;
+/**
+ * Returns all currently active (non-expired) bypass records.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @returns Array of active bypass records.
+ * @example
+ * ```typescript
+ * import { getActiveBypasses } from "@forge-ts/core";
+ * const active = getActiveBypasses("/path/to/project");
+ * console.log(`${active.length} active bypass(es)`);
+ * ```
+ * @public
+ */
+declare function getActiveBypasses(rootDir: string): BypassRecord[];
+/**
+ * Checks whether a specific rule has an active bypass.
+ *
+ * A rule is considered bypassed if there is an active bypass with the exact
+ * rule code or an "all" bypass.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @param ruleCode - The rule code to check (e.g., "E009", "E010").
+ * @returns `true` if the rule is currently bypassed.
+ * @example
+ * ```typescript
+ * import { isRuleBypassed } from "@forge-ts/core";
+ * if (isRuleBypassed("/path/to/project", "E009")) {
+ *   console.log("E009 is currently bypassed");
+ * }
+ * ```
+ * @public
+ */
+declare function isRuleBypassed(rootDir: string, ruleCode: string): boolean;
+/**
+ * Returns the number of bypass budget slots remaining for today.
+ *
+ * Counts bypasses created today (UTC) against the configured daily budget.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @param config - Optional bypass budget configuration overrides.
+ * @returns Number of remaining bypass slots for today.
+ * @example
+ * ```typescript
+ * import { getRemainingBudget } from "@forge-ts/core";
+ * const remaining = getRemainingBudget("/path/to/project");
+ * console.log(`${remaining} bypass(es) remaining today`);
+ * ```
+ * @public
+ */
+declare function getRemainingBudget(rootDir: string, config?: Partial<BypassConfig>): number;
+/**
+ * Removes expired bypass records from `.forge-bypass.json`.
+ *
+ * Also appends a `bypass.expire` audit event for each expired record removed.
+ *
+ * @param rootDir - Absolute path to the project root directory.
+ * @returns The number of expired records removed.
+ * @example
+ * ```typescript
+ * import { expireOldBypasses } from "@forge-ts/core";
+ * const removed = expireOldBypasses("/path/to/project");
+ * console.log(`${removed} expired bypass(es) removed`);
+ * ```
+ * @public
+ */
+declare function expireOldBypasses(rootDir: string): number;
+
 /**
  * Visibility levels for exported symbols.
  * Derived from TSDoc release tags (@public, @beta, @internal).
@@ -54,6 +304,12 @@ interface ForgeSymbol {
             target: string;
             line: number;
         }>;
+        /** TSDoc parser messages (syntax warnings/errors) from @microsoft/tsdoc. */
+        parseMessages?: Array<{
+            messageId: string;
+            text: string;
+            line: number;
+        }>;
     };
     /** Human-readable type signature of the symbol. */
     signature?: string;
@@ -90,6 +346,32 @@ interface EnforceRules {
     "require-class-member-doc": RuleSeverity;
     /** E007: Interface/type member missing documentation. */
     "require-interface-member-doc": RuleSeverity;
+    /** W006: TSDoc syntax parse error (invalid tag, malformed block, etc.). */
+    "require-tsdoc-syntax": RuleSeverity;
+    /** E013: Exported function/class is missing a @remarks block. */
+    "require-remarks": RuleSeverity;
+    /** E014: Optional property with default is missing @defaultValue. */
+    "require-default-value": RuleSeverity;
+    /** E015: Generic symbol is missing @typeParam for its type parameters. */
+    "require-type-param": RuleSeverity;
+    /** W005: Symbol references other symbols via {@link} but has no @see tags. */
+    "require-see": RuleSeverity;
+    /** E016: Exported symbol is missing a release tag (@public, @beta, @internal). */
+    "require-release-tag": RuleSeverity;
+    /** W007: Guide FORGE:AUTO section references a symbol that no longer exists or has changed. */
+    "require-fresh-guides": RuleSeverity;
+    /** W008: Exported public symbol is not mentioned in any guide page. */
+    "require-guide-coverage": RuleSeverity;
+    /** E017: @internal symbol re-exported through public barrel (index.ts). */
+    "require-internal-boundary": RuleSeverity;
+    /** E018: @route-tagged function missing @response tag. */
+    "require-route-response": RuleSeverity;
+    /** W009: {@inheritDoc} references a symbol that does not exist. */
+    "require-inheritdoc-source": RuleSeverity;
+    /** W010: @breaking without @migration path. */
+    "require-migration-path": RuleSeverity;
+    /** W011: New public export missing @since version tag. */
+    "require-since": RuleSeverity;
 }
 /**
  * Full configuration for a forge-ts run.
@@ -171,6 +453,71 @@ interface ForgeConfig {
          */
         extraGotchas?: string[];
     };
+    /** TSDoc ecosystem configuration. */
+    tsdoc: {
+        /** Write tsdoc.json to project root during init. Default: true */
+        writeConfig: boolean;
+        /** Custom tag definitions beyond the forge-ts preset. */
+        customTags: Array<{
+            tagName: string;
+            syntaxKind: "block" | "inline" | "modifier";
+        }>;
+        /** Enforcement level per standardization group. */
+        enforce: {
+            /** Core tags (e.g. @param, @returns, @remarks). Default: "error" */
+            core: "error" | "warn" | "off";
+            /** Extended tags (e.g. @example, @throws, @see). Default: "warn" */
+            extended: "error" | "warn" | "off";
+            /** Discretionary tags (@alpha, @beta, @public, @internal). Default: "off" */
+            discretionary: "error" | "warn" | "off";
+        };
+    };
+    /** Bypass budget configuration for temporary rule overrides. */
+    bypass: {
+        /** Maximum number of bypasses allowed per calendar day. Default: 3 */
+        dailyBudget: number;
+        /** Duration in hours before a bypass automatically expires. Default: 24 */
+        durationHours: number;
+    };
+    /** Guide generation configuration. */
+    guides: {
+        /** Enable intelligent guide generation. Default: true */
+        enabled: boolean;
+        /** Auto-discover guide topics from code analysis. Default: true */
+        autoDiscover: boolean;
+        /** Explicit guide definitions (supplement auto-discovered guides). */
+        custom: Array<{
+            /** URL slug for the guide (e.g., "authentication") */
+            slug: string;
+            /** Human-readable title */
+            title: string;
+            /** Glob patterns for source files to analyze */
+            sources: string[];
+        }>;
+    };
+    /** Downstream config drift guards. */
+    guards: {
+        /** tsconfig.json strictness validation. */
+        tsconfig: {
+            enabled: boolean;
+            /** Required strict-mode flags. Default: ["strict", "strictNullChecks", "noImplicitAny"] */
+            requiredFlags: string[];
+        };
+        /** Biome config drift detection. */
+        biome: {
+            enabled: boolean;
+            /** Biome rules that must stay at error level. Auto-detected on lock. */
+            lockedRules: string[];
+        };
+        /** package.json guards. */
+        packageJson: {
+            enabled: boolean;
+            /** Minimum Node.js version in engines field. */
+            minNodeVersion: string;
+            /** Required fields in package.json. */
+            requiredFields: string[];
+        };
+    };
     /**
      * Warnings generated during config loading (e.g., unknown keys).
      * Populated by loadConfig(). Agents should surface these in output.
@@ -289,6 +636,150 @@ declare function defaultConfig(rootDir: string): ForgeConfig;
  */
 declare function loadConfig(rootDir?: string): Promise<ForgeConfig>;
 
+/**
+ * Config locking system for forge-ts.
+ *
+ * Prevents LLM agents from silently weakening project settings by snapshotting
+ * the current config state and validating it on every subsequent run.
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+/**
+ * Manifest stored in `.forge-lock.json`.
+ * Captures a point-in-time snapshot of the project's forge-ts configuration
+ * so that future runs can detect when settings have been weakened.
+ *
+ * @public
+ */
+interface ForgeLockManifest {
+    /** Schema version of the lock manifest. */
+    version: string;
+    /** ISO-8601 timestamp when the lock was created. */
+    lockedAt: string;
+    /** Identifier of the user or agent that created the lock. */
+    lockedBy: string;
+    /** Snapshot of locked configuration values. */
+    config: {
+        /** Rule name to severity mapping from enforce.rules. */
+        rules: Record<string, string>;
+        /** tsconfig guard settings, if readable at lock time. */
+        tsconfig?: Record<string, unknown>;
+        /** Biome guard settings, if readable at lock time. */
+        biome?: Record<string, unknown>;
+    };
+}
+/**
+ * A single violation found when comparing current config against the lock.
+ *
+ * @public
+ */
+interface LockViolation {
+    /** Dot-path of the config field that changed (e.g., "rules.require-summary"). */
+    field: string;
+    /** The value stored in the lock file. */
+    locked: string;
+    /** The current value in the live config. */
+    current: string;
+    /** Human-readable explanation of the violation. */
+    message: string;
+}
+/**
+ * Reads the `.forge-lock.json` file from the given project root.
+ *
+ * @param rootDir - Absolute path to the project root.
+ * @returns The parsed lock manifest, or `null` if no lock file exists or is invalid.
+ * @example
+ * ```typescript
+ * import { readLockFile } from "@forge-ts/core";
+ * const lock = readLockFile("/path/to/project");
+ * if (lock) {
+ *   console.log(`Locked at ${lock.lockedAt} by ${lock.lockedBy}`);
+ * }
+ * ```
+ * @public
+ */
+declare function readLockFile(rootDir: string): ForgeLockManifest | null;
+/**
+ * Writes a {@link ForgeLockManifest} to `.forge-lock.json` in the project root.
+ *
+ * @param rootDir - Absolute path to the project root.
+ * @param manifest - The lock manifest to write.
+ * @example
+ * ```typescript
+ * import { writeLockFile, createLockManifest, loadConfig } from "@forge-ts/core";
+ * const config = await loadConfig("/path/to/project");
+ * const manifest = createLockManifest(config);
+ * writeLockFile("/path/to/project", manifest);
+ * ```
+ * @public
+ */
+declare function writeLockFile(rootDir: string, manifest: ForgeLockManifest): void;
+/**
+ * Removes the `.forge-lock.json` file from the project root.
+ *
+ * @param rootDir - Absolute path to the project root.
+ * @returns `true` if the file existed and was removed, `false` otherwise.
+ * @example
+ * ```typescript
+ * import { removeLockFile } from "@forge-ts/core";
+ * const removed = removeLockFile("/path/to/project");
+ * console.log(removed ? "Lock removed" : "No lock file found");
+ * ```
+ * @public
+ */
+declare function removeLockFile(rootDir: string): boolean;
+/**
+ * Creates a {@link ForgeLockManifest} from the current project config.
+ *
+ * Snapshots the enforce rule severities and guard settings so they can
+ * be compared on future runs to detect weakening.
+ *
+ * @param config - The fully-resolved {@link ForgeConfig} to snapshot.
+ * @param lockedBy - Identifier of the user or agent creating the lock. Defaults to `"forge-ts lock"`.
+ * @returns A new lock manifest ready to be written with {@link writeLockFile}.
+ * @example
+ * ```typescript
+ * import { createLockManifest, loadConfig } from "@forge-ts/core";
+ * const config = await loadConfig();
+ * const manifest = createLockManifest(config);
+ * console.log(manifest.config.rules); // { "require-summary": "error", ... }
+ * ```
+ * @public
+ */
+declare function createLockManifest(config: ForgeConfig, lockedBy?: string): ForgeLockManifest;
+/**
+ * Validates the current config against a locked manifest.
+ *
+ * Returns an array of violations where the current config has weakened
+ * settings relative to the locked state. Weakening means:
+ * - A rule severity changed from `"error"` to `"warn"` or `"off"`
+ * - A rule severity changed from `"warn"` to `"off"`
+ * - A tsconfig guard was disabled
+ * - A required tsconfig flag was removed
+ * - A biome guard was disabled
+ * - A locked biome rule was removed
+ *
+ * @param config - The current fully-resolved {@link ForgeConfig}.
+ * @param lock - The lock manifest to validate against.
+ * @returns An array of {@link LockViolation} entries. Empty means no weakening detected.
+ * @example
+ * ```typescript
+ * import { validateAgainstLock, readLockFile, loadConfig } from "@forge-ts/core";
+ * const config = await loadConfig();
+ * const lock = readLockFile(config.rootDir);
+ * if (lock) {
+ *   const violations = validateAgainstLock(config, lock);
+ *   for (const v of violations) {
+ *     console.error(`LOCK VIOLATION: ${v.message}`);
+ *   }
+ * }
+ * ```
+ * @public
+ */
+declare function validateAgainstLock(config: ForgeConfig, lock: ForgeLockManifest): LockViolation[];
+
 /**
  * OpenAPI 3.2 type contracts shared across the forge-ts toolchain.
  *
@@ -544,6 +1035,25 @@ declare function meetsVisibility(candidate: Visibility, minVisibility: Visibilit
  */
 declare function filterByVisibility(symbols: ForgeSymbol[], minVisibility: Visibility): ForgeSymbol[];
 
+/** Clears the TSDoc configuration cache. Intended for use in tests only. @internal */
+declare function clearTSDocConfigCache(): void;
+/**
+ * Resolve the TSDoc configuration to use when parsing comments in
+ * files under `folderPath`.
+ *
+ * If a `tsdoc.json` file exists in or above the folder and can be loaded
+ * without errors, its settings are applied to a fresh `TSDocConfiguration`
+ * via `TSDocConfigFile.configureParser()`. Otherwise the default
+ * `TSDocConfiguration` is returned (backward-compatible behaviour).
+ *
+ * Results are cached per folder path so the file system is only consulted
+ * once per unique directory.
+ *
+ * @param folderPath - Absolute directory path of the source file being parsed.
+ * @returns A configured `TSDocConfiguration` instance.
+ * @internal
+ */
+declare function loadTSDocConfiguration(folderPath: string): TSDocConfiguration;
 /**
  * The return type of {@link createWalker}.
  * @public
@@ -577,4 +1087,4 @@ interface ASTWalker {
  */
 declare function createWalker(config: ForgeConfig): ASTWalker;
 
-export { type ASTWalker, type EnforceRules, type ForgeConfig, type ForgeError, type ForgeResult, type ForgeSymbol, type ForgeWarning, type OpenAPIDocument, type OpenAPIEncodingObject, type OpenAPIInfoObject, type OpenAPIMediaTypeObject, type OpenAPIOperationObject, type OpenAPIParameterObject, type OpenAPIPathItemObject, type OpenAPIResponseObject, type OpenAPISchemaObject, type OpenAPITagObject, type RuleSeverity, Visibility, createWalker, defaultConfig, filterByVisibility, loadConfig, meetsVisibility, resolveVisibility };
+export { type ASTWalker, type AuditEvent, type AuditEventType, type BypassConfig, type BypassRecord, type EnforceRules, type ForgeConfig, type ForgeError, type ForgeLockManifest, type ForgeResult, type ForgeSymbol, type ForgeWarning, type LockViolation, type OpenAPIDocument, type OpenAPIEncodingObject, type OpenAPIInfoObject, type OpenAPIMediaTypeObject, type OpenAPIOperationObject, type OpenAPIParameterObject, type OpenAPIPathItemObject, type OpenAPIResponseObject, type OpenAPISchemaObject, type OpenAPITagObject, type ReadAuditOptions, type RuleSeverity, Visibility, appendAuditEvent, clearTSDocConfigCache, createBypass, createLockManifest, createWalker, defaultConfig, expireOldBypasses, filterByVisibility, formatAuditEvent, getActiveBypasses, getCurrentUser, getRemainingBudget, isRuleBypassed, loadConfig, loadTSDocConfiguration, meetsVisibility, readAuditLog, readLockFile, removeLockFile, resolveVisibility, validateAgainstLock, writeLockFile };