studio-typescript
Use when building, checking, linting, formatting, or configuring a TypeScript project with @jterrazz/typescript, such as build/dev/start/mutation, a failing `typescript check` pass, the kind and platform of `studio.config.ts`, its presets and tool settings, the derived editor files, the baseline (`.studio/baseline.json`), writing a rule with `@jterrazz/typescript/rules`.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- studio-typescript
- description
- Use when building, checking, linting, formatting, or configuring a TypeScript project with @jterrazz/typescript, such as build/dev/start/mutation, a failing `typescript check` pass, the kind and platform of `studio.config.ts`, its presets and tool settings, the derived editor files, the baseline (`.studio/baseline.json`), writing a rule with `@jterrazz/typescript/rules`.
03 SKILL.md 正文
@jterrazz/typescript
One devDependency that builds, checks, lints and formats a project. The manual is the package's docs/, read from the install (node_modules/@jterrazz/typescript/docs/) or from this repository when the toolchain itself is the change. This page decides what to run and which page to open; the page owns the rule.
What to run
| Gesture | When |
|---|---|
typescript fix |
before every commit: lint fixes, formatting, .gitignore, spellings, empty directories |
typescript check |
the gate: every pass in parallel, then the drift report; a tree already proven green answers from .artifacts/proven/ and runs nothing, --cold runs it (docs/reference/quality-checks.md, A tree proven green) |
typescript test |
the make test recipe: the project's test script over the test files the change reaches by the last mutation record, every file where it cannot tell (docs/reference/quality-checks.md, The test files a change reaches), answered from its proof like check |
typescript build |
what the manifest publishes into dist/: ESM + types, CJS where a target is .cjs |
typescript mutation |
Stryker over a sandbox copy; fails on a mutant a test runs and lets live (the module tests over the change, then the whole suite over what they let live and the changed lines; domain at zero survivors, glue at its bar; the text of a file typescript.mutation.presentation declares never mutated; --since, --mutate, --report html for the HTML report a person browses; its test runners sized from the machine, TYPESCRIPT_CAPACITY to give it one); a survivor to answer: docs/guides/triage-a-survivor.md |
typescript doctor |
first read after a bump: installed tools against the declared ranges, then every setting beside the file it comes from |
typescript baseline |
a bump lands red: record today's counts, exact; fix lowers one that fell |
typescript docs-layout |
a repository with no npm project: the manual's shape, alone |
typescript gate-lock |
before an install or a pack: refuses while a running gate holds the checkout, naming its pid |
typescript rehearse |
before a tag: the gate on Linux, in Docker, on a fresh clone of the branch, as the runner runs it (docs/reference/commands.md) |
typescript <command> --help prints a command's flags and runs nothing; a flag it does not read, or one given twice, is refused before anything is written (docs/reference/commands.md).
A project declares its kind (library, api, cli, website, mobile) and its platform (node, bun, react, next, astro, expo) in studio.config.ts, defineConfig({ kind, platform }); the profile, the tsconfig preset and every law follow. A monorepo is no kind: its root package.json lists workspaces, is private, and its studio.config.ts holds the repository's settings and no kind, or is absent; each member declares its own. oxlint.config.ts, oxfmt.config.ts and tsconfig.json are derived (the first two hand their own import.meta.url to oxlintConfig / oxfmtConfig), and typescript fix writes them; every tool setting lives in studio.config.ts, and no knip.json, tsdown.config.ts or stryker.config.* is kept. A repository root also owes a Makefile of six gestures and a docs/ manual its CLAUDE.md routes to. The whole wiring, from an empty folder to a green run, is docs/start/getting-started.md.
What a failing pass means
Every pass that ran prints a RUN header and one verdict with its seconds; a pass that did not apply prints nothing. The run's last line names the first failing pass and its first finding, and .artifacts/gate/verdict.json holds every pass's status for a reader that should not parse the log, for check, fix and mutation alike (docs/reference/quality-checks.md, The verdict file). Each rule id below is explained in docs/reference/quality-checks.md, under the pass's own section. On a GitHub runner the run prints a line per pass, each finding as rule and place, found, fix and read, and an annotation each (docs/reference/quality-checks.md, On a GitHub runner).
| Pass | It failed because |
|---|---|
| Config (one file) | studio.config.ts declares no valid kind and platform, a derived file says something else (typescript fix), a tool keeps its own config, the manifest does not match the kind, or a src/standard/ computes |
| TypeScript Check | tsc 7 refused a type |
| Oxlint Check | a rule fired that .studio/oxlint-suppressions.json does not hold: fix it, or typescript baseline; a recorded count fell: typescript fix; an oxlint rule is left in .studio/baseline.json (baseline-moved-to-oxlint): typescript baseline; a directive suppresses nothing (Unused oxlint-disable directive, reportUnusedDisableDirectives): delete it; a @ts-ignore or an undescribed @ts-expect-error (typescript/ban-ts-comment) |
| Oxfmt Check | a file is not formatted: typescript fix |
| Gitignore (artefacts) | an artefact is named or committed outside .artifacts/<tool>/ |
| Knip (unused code) | a file, export or dependency nothing uses |
| a preset's label | a preset's checks refused, @jterrazz/test's conventions among them; the preset's own manual owns the id |
| Docs (layout) | the repository's docs/ breaks the manual's spine, or holds a generated reference/ |
| Publish (packaging) | the exports map promises a file the tarball does not carry, or a shipped file is compiled from test material |
| Architecture (layer map) | an import crosses a layer of a preset (the standard's lint/ direction included), of typescript.architecture or of the project's own .dependency-cruiser.* (architecture/<name>, at its line); a recorded architecture/<name> count grew (typescript baseline) or fell (typescript fix); the map does not load or has nothing to cruise |
| Astro (check + format) | astro check or prettier refused a .astro file |
| Suppressions (directives) | a lint directive is misspelled or unreasoned |
| Comments (styles, scripts, YAML) | a comment of a style sheet, a script, a Makefile, a Dockerfile or a YAML file states no kind: give it one, or delete it by hand, since typescript fix deletes no comment |
| Markdown (prose) | rumdl refused a page (markdown/link-resolves a missing link, MD051 a missing anchor, MD040 a fence with no language: typescript fix), a page cites a path that is gone, a block runs past its limit, a skill's frontmatter is no YAML or lacks its name or description (markdown/skill-frontmatter-reads: quote the value holding : ), or its prose punctuates with a dash (markdown/prose-has-no-dash: rewrite the sentence; an author's text kept as written sits under a root declared { reason, verbatim: true }) |
| Names (tree) | a directory is not kebab-case, a name says nothing, names a construct (types.ts), is written in half, a skill holds more than its SKILL.md, a root sits outside the spine undeclared, studio.config.ts does not load, an entry is not named for its subpath, an index publishes nothing, a .bin publishes no bin, a published subpath has no source, the Makefile misses one of the six gestures, or a directory is empty: typescript fix |
| Secrets (credentials) | a committed line looks like a live credential |
The drift report closes the run, and refuses nothing: a rule set apart already carries its reason in typescript.oxlint.
Before writing
- A file is named for its subject in the domain: never
types.ts,utils.ts,constants.ts, nor a*.types.tssuffix. Anindexis an entry the package publishes, namedindex[.<subpath>][.browser].tsfor its subpath, and a bin<command>.bin.ts, named for the command it publishes..binmarks only a published bin, and a program the package does not publish is named for what it runs (docs/reference/quality-checks.md, The entry grammar). - A file holds 300 lines and a function 60; a
*.spec.tsis@jterrazz/test'sspec-file-within-line-limit, at 400 (docs/reference/lint-presets.md). - The default is no comment: a name carries the meaning. A comment that stays opens with its kind (
invariant:,hazard:,outside:orvalue:) or failsjterrazz-typescript/comment-states-its-kind, which you settle by hand, sincetypescript fixdeletes no comment; an exported symbol's hover is one/** ... */paragraph above it, wrapped with no blank line, which its block tags (@param,@example) may follow on lines of their own. A style sheet's, a script's, a Makefile's, a Dockerfile's and a YAML file's comments are held to the same kinds by the Comments pass. A comment longer than the function it sits on failsjterrazz-typescript/comment-no-longer-than-its-function(docs/reference/lint-presets.md, A comment states its kind). - A suppression carries its reason:
// oxlint-disable-next-line <rule> -- why, and@ts-expect-errorwith a description. - Every artefact lives under
.artifacts/<tool>/;dist/is the product, not an artefact. - What knip cannot trace goes under
typescript.knip, each name mapped to its reason. - The API is the types: there is no generated reference, and
docs/never holds one. - A repository root holds
src/,lint/,specs/,docs/,skills/; any other root folder fails Names (tree) unless the ecosystem imposes it (bin/,public/,app/...) orstudio.config.tsdeclares it undertypescript.rootswith a reason. - A
lint/holds at its root the modules that compose it (its entries, its bins, whatsrc/reads) and three folders:consumer/andself/hold declarations alone, andkit/holds the code that runs them (docs/reference/quality-checks.md, The lint tree). - A repository's root
Makefileanswersmake install,build,lint,fix,testandcheck; a workspace member owes none of them. studio.config.tsholds what the project is, its presets and its exceptions, each with its reason, and nothing derivable: a module loaded by path is built by its name (instrumentation.ts,*.worker.ts,*.global-setup.ts, a*.cli.tsinto.artifacts/dev/), and kind and platform defaults are the standard's (docs/reference/building.md, What the manifest does not name).- What a package holds a project to reaches it through the preset the project lists under
presetsinstudio.config.ts, after the standard the declaration derives; the project's own layers, roots and name rules go in itstypescriptsection, and a preset's law is set aside only underoptOuts, with its reason (docs/reference/configuration.md, Presets). - A rule a package writes for its consumers is written with
@jterrazz/typescript/rules(docs/reference/rules-kit.md). - A local
compilerOptionis a smell: the preset is where the fix belongs.
The page to read next
| Question | Page |
|---|---|
| what the toolchain is, and the map of the manual | README.md, then docs/README.md |
| the four ideas: declaration, settings file, two commands, baseline | docs/concepts/ideas.md |
wiring a project from an empty folder to a green check, .artifacts/ |
docs/start/getting-started.md |
studio.config.ts, kind and platform, a preset, the merge order, an opt-out, a rule set apart, a tsconfig preset |
docs/reference/configuration.md |
| a failing pass, a rule id, the baseline | docs/reference/quality-checks.md |
| a lint rule, a profile, how the config merges, knip | docs/reference/lint-presets.md |
build, start, dev, tsc, an entry the manifest does not name |
docs/reference/building.md |
| a bump landed red | docs/guides/adopt-a-stricter-release.md |
proving a release on a project before it is published: the tarball install, no install-links |
docs/guides/install-an-unreleased-build.md |
| which number moves on a release | docs/guides/release.md |
| writing a rule, a check or its page with the kit | docs/reference/rules-kit.md |
| changing the toolchain itself: its layers, its loop | docs/concepts/architecture.md, docs/guides/develop.md |
| how this toolchain proves itself, and the rules it keeps for its own suite (this repository alone; the install ships without it) | docs/guides/test.md |
04 同仓库更多 Skills
shop
Use when working on the shop.
x
x
shop
Use when working on the shop.
shop
Use when working on the shop.
shop
Use when: an order is placed.
returns
暂无简介