core — Examples
Usage examples for the core package
All usage examples from the package, aggregated for quick reference.
getCurrentUser()
Returns the current OS username, or "unknown" if unavailable.
import { getCurrentUser } from "@forge-ts/core/audit";
const user = getCurrentUser(); // e.g. "alice"appendAuditEvent()
Appends a single audit event to the .forge-audit.jsonl file.
import { appendAuditEvent } from "@forge-ts/core";
const event = { timestamp: new Date().toISOString(), event: "config.lock" as const, user: "alice", reason: "Stabilize", details: {} };
appendAuditEvent("/path/to/project", event);readAuditLog()
Reads the .forge-audit.jsonl file and returns parsed audit events.
import { readAuditLog } from "@forge-ts/core";
const events = readAuditLog("/path/to/project", { limit: 10 });
console.log(events.length); // up to 10formatAuditEvent()
Formats a single audit event as a human-readable string.
import { formatAuditEvent } from "@forge-ts/core";
const event = { timestamp: "2026-03-21T12:00:00.000Z", event: "config.lock" as const, user: "alice", reason: "Stabilize", details: {} };
const line = formatAuditEvent(event);
console.log(line);createBypass()
Creates a new bypass record, writes it to .forge-bypass.json, and appends an audit event.
import { createBypass } from "@forge-ts/core";
const bypass = createBypass("/path/to/project", "hotfix for release", "E009", { dailyBudget: 5, durationHours: 12 });
console.log(bypass.id);getActiveBypasses()
Returns all currently active (non-expired) bypass records.
import { getActiveBypasses } from "@forge-ts/core";
const active = getActiveBypasses("/path/to/project");
console.log(`${active.length} active bypass(es)`);isRuleBypassed()
Checks whether a specific rule has an active bypass.
import { isRuleBypassed } from "@forge-ts/core";
if (isRuleBypassed("/path/to/project", "E009")) {
console.log("E009 is currently bypassed");
}getRemainingBudget()
Returns the number of bypass budget slots remaining for today.
import { getRemainingBudget } from "@forge-ts/core";
const remaining = getRemainingBudget("/path/to/project", { dailyBudget: 5, durationHours: 24 });
console.log(`${remaining} bypass(es) remaining today`);expireOldBypasses()
Removes expired bypass records from .forge-bypass.json.
import { expireOldBypasses } from "@forge-ts/core";
const removed = expireOldBypasses("/path/to/project");
console.log(`${removed} expired bypass(es) removed`);ForgeConfig
Full configuration for a forge-ts run.
// forge-ts.config.ts
import { defineConfig } from "@forge-ts/core";
export default defineConfig({
outDir: "docs/generated",
enforce: { strict: true },
gen: { formats: ["mdx"], ssgTarget: "fumadocs" },
});defineConfig()
Type-safe helper for defining a partial forge-ts configuration.
import { defineConfig } from "@forge-ts/core";
const config = { outDir: "docs", enforce: { strict: true } };
export default defineConfig(config);defaultConfig()
Constructs a sensible default ForgeConfig rooted at rootDir.
import { defaultConfig } from "@forge-ts/core";
const config = defaultConfig("/path/to/project");
console.log(config.enforce.enabled); // trueloadConfig()
Loads the forge-ts configuration for a project.
import { loadConfig } from "@forge-ts/core";
const config = await loadConfig("/path/to/project");
// config is fully resolved with defaultsreadLockFile()
Reads the .forge-lock.json file from the given project root.
import { readLockFile } from "@forge-ts/core";
const lock = readLockFile("/path/to/project");
if (lock) {
console.log(`Locked at ${lock.lockedAt} by ${lock.lockedBy}`);
}writeLockFile()
Writes a ForgeLockManifest to .forge-lock.json in the project root.
import { writeLockFile, createLockManifest, loadConfig } from "@forge-ts/core";
const config = await loadConfig("/path/to/project");
const manifest = createLockManifest(config, "alice");
writeLockFile("/path/to/project", manifest);removeLockFile()
Removes the .forge-lock.json file from the project root.
import { removeLockFile } from "@forge-ts/core";
const removed = removeLockFile("/path/to/project");
console.log(removed ? "Lock removed" : "No lock file found");createLockManifest()
Creates a ForgeLockManifest from the current project config.
import { createLockManifest, loadConfig } from "@forge-ts/core";
const config = await loadConfig();
const manifest = createLockManifest(config, "alice");
console.log(manifest.config.rules);validateAgainstLock()
Validates the current config against a locked manifest.
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}`);
}
}resolveVisibility()
Determines the visibility level of a symbol from its TSDoc release tags.
import { resolveVisibility } from "@forge-ts/core";
const vis = resolveVisibility({ internal: [] });
// vis === Visibility.InternalmeetsVisibility()
Returns whether candidate meets or exceeds the required minimum visibility.
import { meetsVisibility, Visibility } from "@forge-ts/core";
meetsVisibility(Visibility.Public, Visibility.Public); // true
meetsVisibility(Visibility.Internal, Visibility.Public); // false
meetsVisibility("public", "beta"); // true (string literals also accepted)filterByVisibility()
Filters an array of ForgeSymbol objects to only include symbols whose visibility meets or exceeds minVisibility.
import { filterByVisibility, Visibility } from "@forge-ts/core";
const publicOnly = filterByVisibility(symbols, Visibility.Public);createWalker()
Creates an ASTWalker configured for the given forge config.
import { loadConfig, createWalker } from "@forge-ts/core";
const config = await loadConfig();
const walker = createWalker(config);
const symbols = walker.walk();
console.log(`Found ${symbols.length} symbols`);index.ts
Foundation package for the forge-ts toolchain — shared types, config loader, and TypeScript AST walker. Every other @forge-ts package depends on this one. It provides the single AST traversal pass (createWalker) that produces a ForgeSymbol[] graph, the config resolution pipeline (loadConfig), and all shared types used across enforcement, generation, and API extraction.
import { loadConfig, createWalker } from "@forge-ts/core";
const config = await loadConfig(); // reads forge-ts.config.ts or defaults
const walker = createWalker(config);
const symbols = walker.walk(); // ForgeSymbol[]
console.log(`Found ${symbols.length} exported symbols`);