Skip to content

Latest commit

 

History

History
113 lines (94 loc) · 6.6 KB

typescript-inventory.md

File metadata and controls

113 lines (94 loc) · 6.6 KB

TypeScript inventory

Repository automation for measuring JavaScript and TypeScript adoption. The collector lives in tools/scripts; it is reporting automation, and does not change or convert source files.

Run pnpm inventory:typescript --output /tmp/ghost-typescript from the root to write /tmp/ghost-typescript.json. Ghost-Benchmarks renders this JSON as the interactive dashboard. Use --scope ghost (or another repository-relative directory) to focus the data. Resolution and dependent counts still consider the whole repository.

The inventory reads tracked working-tree JS/JSX/TS/TSX files, including .mjs, .cjs, .mts, and .cts. It includes maintained fixture modules and test helpers. It excludes submodules, untracked files, snapshot directories, vendor directories, build/dist/coverage output, minified JavaScript, the package template, and SimpleMDE's generated debug bundles. Explicit test-input exclusions cover Core's assets-minification fixture directory, the bundled Casper/Source theme assets under test fixtures, and sloppy-config-writer.js, which deliberately exercises non-strict JavaScript. Other files are not excluded merely because their directory is named fixtures.

measurementVersion: 2 identifies these counting rules separately from the JSON schema. Reports without this field used the earlier fixture exclusion and are not directly comparable. Ghost-Benchmarks recounts historical revisions with the current rules instead of combining different counting baselines.

Declaration files are counted separately. Exclusion paths and declaration totals are repository-wide, even in scoped reports. Percentages compare implementation files and physical lines (including comments and blanks); they do not measure type safety or enforce conversion of intentional JavaScript tooling.

Files are grouped by their nearest package manifest. Tests and tooling use path and filename conventions; these categories are approximate. Production is split into frontend (apps/, Koenig's three editor UI packages, and Core's core/frontend/public/ browser scripts) and backend (remaining server code and library packages, including libraries shared with the frontend). Core's core/frontend/ routing and rendering code executes on the server and therefore belongs to backend. Tests and tooling take precedence over this split.

Tooling uses recognised tool config filenames (including dotfiles), explicit build helpers, the shared tools/configs/ packages, scripts and CI configuration. Runtime configuration is not tooling merely because its name contains config. Runner configs such as e2e/playwright.config.mjs are tooling; actual tests remain tests.

Test support includes test-utils, __fixtures__ and packages/testing/; backend schema fixtures remain backend code. JSON schema version 2 replaces the old production category with these two values.

Static imports, re-exports, literal dynamic imports, and require() calls are parsed with the TypeScript compiler API. Dependency resolution uses the nearest tracked tsconfig.json, including inherited options, or NodeNext defaults when absent. Resolution runs with allowJs to identify JavaScript dependencies. The report shows the configuration and resolved path for each dependency. Node built-ins are marked typed only when Node declarations resolve from the importing file.

Difficulty is a transparent triage heuristic:

  • Each dependency resolving to JavaScript adds 3 points.
  • Each unresolved dependency or built-in without available Node types adds 5.
  • Each computed import or require adds 5.
  • Each 100 physical lines and each 5 functions adds 1 (rounded up).
  • CommonJS adds 2; each parse error adds 10.
  • Scores up to 5 are easier, up to 15 moderate, and above 15 harder.

Repeated imports are deduplicated by specifier and import/require mode. Direct callers are listed separately to show conversion impact. This is a static module graph: runtime loading and shadowed require calls are not resolved semantically. Cycles, ambient module declarations, JSDoc quality, bundler-specific resolution, and business complexity are not assessed. Missing builds or dependencies can produce unresolved imports; available declarations can still contain any. Inspect the evidence before choosing a conversion. The report neither executes source modules nor queries package registries.

The implementation follows TypeScript's module resolution reference and compiler API. Run its tests with pnpm --filter @internal/scripts exec node --test test/typescript-inventory.test.ts.

Published reports

The TypeScript inventory workflow runs independently on every push to main. It installs locked dependencies and builds workspace declarations before scanning, then retains the JSON as a typescript-inventory artifact for 30 days. Runs do not cancel each other. Each push measures its head commit; commits batched into a single push do not each get a separate measurement.

After a successful run, a separate workflow dispatches its run ID to Ghost-Benchmarks using the existing cross-repository publishing credential. The receiver verifies the source run before publishing the latest report at TypeScript inventory. It retains compact per-commit counts in typescript/history.json. Older runs can add history without replacing a newer report. Failed scans leave the last published report intact; rerun the failed workflow to retry. Publishing requires the receiver workflow to be installed on Ghost-Benchmarks main first.

Historical counts and PR comparisons

pnpm inventory:typescript --root /path/to/Ghost --revision <ref> --output /tmp/counts reads committed Git blobs with the current collector and produces a counts-only JSON report (mode: "counts-only"). It does not check out or execute historical source, install dependencies, resolve imports or assign conversion difficulty. The output includes the full source SHA, commit timestamp, summary, package and kind totals. Submodules and symlinks are not traversed. The ordinary command continues to scan tracked working-tree source with dependency analysis.

For a PR, collect its merge base and head with the same version of this command and subtract counts. This does not depend on a previously published report. Ghost-Benchmarks owns the HTML renderer, graph, history and local backfill command; see its docs/dashboard.md. Deploy its JSON-capable publisher before removing HTML output from Ghost. No PR comment job is introduced by this split.