{"id":47597654,"url":"https://github.com/kryptobaseddev/forge-ts","last_synced_at":"2026-04-01T18:27:16.989Z","repository":{"id":345385988,"uuid":"1185694545","full_name":"kryptobaseddev/forge-ts","owner":"kryptobaseddev","description":"The universal documentation compiler for any TypeScript project","archived":false,"fork":false,"pushed_at":"2026-03-26T15:41:16.000Z","size":1820,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T01:16:59.888Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kryptobaseddev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["kryptobaseddev"]}},"created_at":"2026-03-18T21:13:59.000Z","updated_at":"2026-03-26T17:03:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kryptobaseddev/forge-ts","commit_stats":null,"previous_names":["kryptobaseddev/forge-ts"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/kryptobaseddev/forge-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fforge-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fforge-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fforge-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fforge-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kryptobaseddev","download_url":"https://codeload.github.com/kryptobaseddev/forge-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fforge-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-01T18:27:16.198Z","updated_at":"2026-04-01T18:27:16.908Z","avatar_url":"https://github.com/kryptobaseddev.png","language":"TypeScript","funding_links":["https://github.com/sponsors/kryptobaseddev"],"categories":[],"sub_categories":[],"readme":"# forge-ts\n\n\u003e The Hallucination Killer. A documentation compiler that FORCES structural clarity in TypeScript.\n\n[![npm version](https://img.shields.io/npm/v/@forge-ts/cli?style=flat-square\u0026label=@forge-ts/cli)](https://www.npmjs.com/package/@forge-ts/cli)\n[![CI](https://img.shields.io/github/actions/workflow/status/kryptobaseddev/forge-ts/ci.yml?style=flat-square\u0026label=CI)](https://github.com/kryptobaseddev/forge-ts/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)\n[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0.2-blue?style=flat-square\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![Node.js: \u003e=24](https://img.shields.io/badge/Node.js-%3E%3D24-brightgreen?style=flat-square\u0026logo=node.js)](https://nodejs.org)\n\nIf it isn't documented, it isn't finished. If the docs are stale, the build is broken.\n\nforge-ts performs a **single AST traversal** of your TypeScript project and compiles TSDoc into OpenAPI specs, executable doctests, AI context files, and SSG-ready documentation. **37 enforcement rules** across 5 layers ensure documentation is never optional, never stale, and never wrong.\n\n---\n\n## Proven Results\n\nforge-ts dogfoods itself. Every claim below is verified by the codebase.\n\n| Metric | Value |\n|--------|-------|\n| Enforcement rules | **37** across 5 layers (API, Dev, Consumer, LLM Anti-Pattern, Staleness) |\n| Symbols checked | **363** across 6 packages |\n| TSDoc errors | **0** (forge-ts passes its own full check) |\n| Tests | **859** passing across 20 test files |\n| Barometer score | **93% (Elite SSoT)** -- a zero-context agent answered 14/15 questions correctly using only generated docs |\n\n### The Barometer Test\n\nWe built `forge-ts barometer` -- a command that generates questions from the AST and tests whether the generated docs are accurate enough for an agent with zero prior context. An agent reading only `llms-full.txt` scored **93%**, proving the vision: code IS the documentation, and forge-ts makes it true.\n\n```\nPre-fix barometer:  35% (Stale/Shallow) -- @remarks silently dropped\nPost-fix barometer: 93% (Elite SSoT)    -- @remarks pipeline restored\n```\n\n---\n\n## Quick Start\n\n```bash\nnpm install -D @forge-ts/cli\n\nnpx forge-ts check            # Lint TSDoc coverage (37 rules)\nnpx forge-ts test              # Run @example blocks as tests\nnpx forge-ts build             # Generate all artifacts in one pass\nnpx forge-ts barometer         # Test documentation effectiveness\nnpx forge-ts doctor            # Validate project setup\n```\n\n---\n\n## What It Generates\n\n```\nYour TypeScript + TSDoc\n        |\n        v\n  forge-ts build\n        |\n   +----+----------------------------------------+\n   |              |              |                |\n   v              v              v                v\nOpenAPI 3.2   Doctests      AI Context       Markdown/MDX\n  specs      (@example     (llms.txt /      (Docusaurus /\n(openapi.json) blocks)    llms-full.txt)    Mintlify /\n                                             Nextra /\n                                             VitePress)\n```\n\n| Output | Description |\n|--------|-------------|\n| **OpenAPI 3.2** | Machine-readable API specs from exported types and `@route` tags |\n| **Doctests** | `@example` blocks extracted and executed via Node 24's `node:test` runner |\n| **AI context** | Token-optimized `llms.txt` and `llms-full.txt` with `@remarks` content for LLM agents |\n| **Markdown/MDX** | SSG-ready docs grouped by package with `@packageDocumentation` summaries |\n| **SKILL packages** | Agent-consumable skill bundles following the agentskills.io spec |\n| **README sync** | Keeps your GitHub front page synchronized with your code |\n\n---\n\n## The Five Pillars\n\n### 1. The Hallucination Killer (Enforcement)\n\nUndocumented code is broken code. forge-ts FORCES explicit `@param`, `@returns`, `@remarks`, and `@example` on every public symbol. Agents can't guess -- they read what's documented.\n\n**37 rules** across 5 layers:\n\n| Layer | Rules | What It Catches |\n|-------|-------|----------------|\n| **API** | E001-E008, W003-W004 | Missing summary, params, returns, examples, package docs, dead links |\n| **Dev** | E013-E015, E017-E018, W005-W006, W009 | Missing @remarks, @typeParam, @see; TSDoc syntax errors |\n| **Consumer** | E016, W007-W008, W010-W011 | Missing release tags, stale guides, undocumented exports |\n| **LLM Anti-Pattern** | E019-E020, W012-W013 | @ts-ignore in non-test files, `any` in public APIs, stale examples |\n| **Staleness** | W014-W017 | @param name drift, param count mismatch, void @returns, placeholder @remarks |\n\n### 2. The Deterministic Layer (Generation)\n\nExtraction \u003e Inference. forge-ts extracts documentation from your AST -- it never guesses, summarizes, or hallucinates. The generated `llms-full.txt` includes full `@remarks` content so agents understand implementation details, not just signatures.\n\n### 3. Agent-Proof Guardrails\n\nAgents take the easy way out. forge-ts blocks the exit.\n\n- **Config Locking**: `forge-ts lock` snapshots rule severities. Weakening them triggers E010.\n- **Audit Trail**: Every change logged to `.forge-audit.jsonl` with user, timestamp, and reason.\n- **Bypass Budget**: 3 bypasses/day max, each requires `--reason` and expires in 24h.\n- **Guard Rules**: E009-E012 detect tsconfig loosening, Biome weakening, engine downgrades.\n\n### 4. Safety Pipeline\n\nPre-commit, not post-mortem.\n\n```bash\nnpx forge-ts init hooks        # Scaffold husky/lefthook pre-commit hooks\nnpx forge-ts prepublish        # Safety gate: check + build before npm publish\n```\n\n### 5. Documentation Effectiveness Testing\n\n```bash\nnpx forge-ts barometer                    # Generate Q\u0026A from AST\nnpx forge-ts barometer --questions-only   # Questions only (for test agents)\n```\n\nThe barometer generates questions from your code, produces an answer key, and scores on a 4-band rubric:\n\n| Score | Rating | Meaning |\n|-------|--------|---------|\n| 90-100% | **Elite SSoT** | Agents operate with zero source code access |\n| 70-89% | **High Fidelity** | Excellent, might miss some @remarks details |\n| 50-69% | **Standard** | Useful for usage, architecture needs source access |\n| 0-49% | **Stale/Shallow** | Needs deeper @remarks and @example coverage |\n\n---\n\n## Agent-First Design\n\nforge-ts is built for LLM agent pipelines. Every command supports `--json` output with LAFS envelopes and machine-readable exit codes.\n\n```bash\n# Structured JSON output for agents and CI\nforge-ts check --json\n\n# Token-efficient minimal output for agentic loops\nforge-ts check --mvi minimal\n\n# Feed generated context directly to your agent\ncat docs/generated/llms-full.txt | your-agent-cli\n```\n\nThe `llms.txt` and `llms-full.txt` outputs follow the [llms.txt standard](https://llmstxt.org), giving any AI assistant accurate, up-to-date context about your project's API surface — including `@remarks` implementation details — without hallucination.\n\n---\n\n## Configuration\n\nZero-config by default. Optionally create `forge-ts.config.ts`:\n\n```typescript\nimport { defineConfig } from \"@forge-ts/core\";\n\nexport default defineConfig({\n  rootDir: \".\",\n  outDir: \"./docs/generated\",\n  enforce: {\n    enabled: true,\n    minVisibility: \"public\",\n    strict: false,\n    rules: {\n      \"require-example\": \"warn\",\n      \"require-remarks\": \"error\",\n    },\n  },\n  doctest: {\n    enabled: true,\n    cacheDir: \".cache/doctest\",\n  },\n  api: {\n    enabled: true,\n    openapi: true,\n    openapiPath: \"./docs/generated/openapi.json\",\n  },\n  gen: {\n    enabled: true,\n    formats: [\"markdown\"],\n    llmsTxt: true,\n    readmeSync: false,\n    ssgTarget: \"mintlify\",\n  },\n});\n```\n\n---\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `forge-ts check` | Lint TSDoc coverage. 37 rules. Supports `--staged` for pre-commit. |\n| `forge-ts test` | Run `@example` blocks as doctests via `node:test`. |\n| `forge-ts build` | Generate OpenAPI, docs, llms.txt, SKILL packages. |\n| `forge-ts barometer` | Generate documentation effectiveness Q\u0026A from AST. |\n| `forge-ts init` | Full project setup: config, tsdoc.json, scripts. |\n| `forge-ts init docs` | Scaffold SSG documentation site. |\n| `forge-ts init hooks` | Scaffold pre-commit hooks (Husky/Lefthook). |\n| `forge-ts docs dev` | Start local doc preview server. |\n| `forge-ts lock` | Snapshot config to prevent drift. |\n| `forge-ts unlock` | Remove lock with mandatory `--reason`. |\n| `forge-ts bypass` | Temporary rule exemption with daily budget. |\n| `forge-ts audit` | View append-only audit trail. |\n| `forge-ts prepublish` | Safety gate: check + build before publish. |\n| `forge-ts doctor` | Validate project setup. Supports `--fix`. |\n| `forge-ts version` | Print version. Also `-V`, `-v`. |\n\nAll commands support `--json` (LAFS envelope), `--human`, `--quiet`, `--mvi`.\n\n### `forge-ts check`\n\nValidates TSDoc coverage across all public exports. Use as a CI build gate.\n\n```bash\nforge-ts check [--strict] [--staged] [--verbose] [--rule E001] [--file src/] [--cwd \u003cdir\u003e]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--strict` | Treat warnings as errors |\n| `--staged` | Only check git-staged `.ts`/`.tsx` files (fast pre-commit) |\n| `--rule E001` | Filter to a specific rule code |\n| `--file src/types.ts` | Filter to files matching substring |\n| `--limit 20` | Max file groups per page (pagination) |\n| `--mvi minimal` | Counts only (~50 tokens) |\n| `--mvi full` | Full details with `suggestedFix` |\n\n### `forge-ts test`\n\nExtracts `@example` blocks and runs them as tests via Node 24's built-in `node:test` runner.\n\n```bash\nforge-ts test [--cwd \u003cdir\u003e]\n```\n\n### `forge-ts build`\n\nGenerates all outputs in a single AST traversal.\n\n```bash\nforge-ts build [--skip-api] [--skip-gen] [--force-stubs] [--cwd \u003cdir\u003e]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--skip-api` | Skip OpenAPI spec generation |\n| `--skip-gen` | Skip Markdown/MDX and llms.txt generation |\n| `--force-stubs` | Overwrite stub pages (reset to scaffolding) |\n\n---\n\n## SSG Targets\n\nSet `gen.ssgTarget` in your config to target your documentation platform:\n\n| Target | Output Format | Description |\n|--------|--------------|-------------|\n| `\"mintlify\"` | MDX | Mintlify docs.json navigation (default) |\n| `\"docusaurus\"` | MDX | Docusaurus sidebar config |\n| `\"nextra\"` | MDX | Nextra v4 App Router with `_meta.json` |\n| `\"vitepress\"` | Markdown | VitePress `.vitepress/config.mts` |\n\n---\n\n## Supported TSDoc Tags\n\n### Standard Tags (enforced)\n\n| Tag | Description |\n|-----|-------------|\n| `@param` | Parameter documentation (E002) |\n| `@returns` | Return value documentation (E003) |\n| `@throws` | Exception documentation |\n| `@example` | Executable code example — becomes a doctest (E004) |\n| `@remarks` | Implementation details for agents (E013) |\n| `@defaultValue` | Default value for optional properties (E014) |\n| `@typeParam` | Generic type parameter documentation (E015) |\n| `@public` | Mark as public API (E016 requires one of public/beta/internal) |\n| `@beta` | Mark as beta / unstable |\n| `@internal` | Exclude from generated docs |\n| `@deprecated` | Mark as deprecated with explanation (W003) |\n| `@see` | Cross-reference to related symbols (W005) |\n| `@since` | Version when symbol was introduced (W011) |\n\n### Custom Tags (15 tags via `@forge-ts/core/tsdoc-preset`)\n\n| Tag | Kind | Description |\n|-----|------|-------------|\n| `@route` | block | HTTP route path for OpenAPI (e.g., `@route GET /api/users`) |\n| `@category` | block | Symbol grouping for guide discovery |\n| `@guide` | block | Associates symbol with a named guide page |\n| `@concept` | block | Links symbol to a concepts page section |\n| `@response` | block | HTTP response type/status for OpenAPI |\n| `@query` | block | Query parameter documentation |\n| `@header` | block | HTTP header documentation |\n| `@body` | block | Request body schema |\n| `@quickstart` | modifier | \"Start here\" marker |\n| `@faq` | block | FAQ entry association |\n| `@breaking` | block | Breaking change documentation (W010 requires `@migration`) |\n| `@migration` | block | Migration path from old API |\n| `@complexity` | block | Algorithmic complexity |\n| `@forgeIgnore` | modifier | Skip all enforcement on this symbol |\n\n---\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| `@forge-ts/core` | TypeScript Compiler API walker, ForgeSymbol graph, config loader, lock/audit/bypass |\n| `@forge-ts/enforcer` | 37 rules across 5 layers with per-rule severity config |\n| `@forge-ts/doctest` | `@example` extraction + Node 24 `node:test` runner |\n| `@forge-ts/api` | OpenAPI 3.2.0 generation from `@route` tags |\n| `@forge-ts/gen` | Markdown/MDX, SSG adapters, llms.txt, SKILL packages, guide discovery |\n| `@forge-ts/cli` | Unified CLI (citty + consola), 15 commands |\n\n---\n\n## Technology\n\n| Tool | Version | Role |\n|------|---------|------|\n| TypeScript | 6.0.2 | Compiler API -- last JS-based release before Go rewrite |\n| Node.js | 24 LTS | Runtime with native TS stripping and stable `node:test` |\n| @microsoft/tsdoc | 0.16 | Standards-compliant TSDoc parsing |\n| @cleocode/lafs | 2026.3.x | LLM-Agent-First output protocol |\n| Biome | 2.4 | Linting + formatting |\n| Vitest | 4.1 | Unit testing |\n| @codluv/versionguard | 0.4 | Version governance |\n\n---\n\n## The Vision\n\nforge-ts exists because LLM agents are primary contributors now, and undocumented code is a liability. Agents can't infer intent from messy code -- they hallucinate. forge-ts eliminates hallucination by forcing explicit, structured documentation at the compiler level, then extracting it deterministically into artifacts that agents consume with zero context.\n\n**Extraction \u003e Inference. Always.**\n\nRead the full vision: [docs/VISION.md](docs/VISION.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptobaseddev%2Fforge-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkryptobaseddev%2Fforge-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptobaseddev%2Fforge-ts/lists"}