@starci/hfs 1.0.1 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 2.0.1 - 2026-10-01
+
+- Fixed: `hfs sync` validates the whole hfs.json declaration against the manifest before rendering (a pre-2.0 `connections` list of names is refused), so a pin bump can never leave eslint unable to start.
+- Changed: the back-end managed scripts carry `test:stack` (`starci-test-stack`); repo-specific devDependencies stay the repository's (sync owns only the `scripts` block and the canon pins).
+
+## 2.0.0 - 2026-09-30
+
+- Added (lane PORT): the repository scripts of the product repos are gone, so their laws live here. `repo.scripts` owns `scripts/{.gitkeep,*.mjs,*.cjs,*.ps1,*.sh}` (operational scripts, or an empty folder with `.gitkeep`, which `hfs sync --init` writes from `templates/{be,fe}/skeleton/scripts/.gitkeep`). New checks: `BE_SPEC_PLACEMENT` (R102, a spec outside the four test layers, `scripts/` and `tools/` included), `HFS_REPO_LOCAL_CHECK` (R103, a `check-*` file, `eslint-local-rules*`, a local plugin, a script that runs one), `HFS_LINT_SUPPRESSION_FILE` (R104, an eslint suppressions file, script or flag), `HFS_PROOF_COMMAND_FILE_MISSING` (R105, a `.starciwork` proof command that runs a file the repository does not hold; only records of this repository are judged) and, in the architecture machine, `FE_I18N_KEYS` (R106, a key the source reads that a locale lacks, a catalog key nothing reads). `HFS_DEP_VERSION_SKEW` (R14) also refuses a dependency declared at another version than the root `overrides` pin.
+- Changed (lane PORT): `hfs work-hygiene` is the secrets guard of the commit for both profiles: every staged file, read from the index, is judged by the one secret judgement of `hfs check` (`secretFileFindings`: a secret by being, an `.enc` that is no sops envelope, a line that matches a secret pattern); the front-end pre-commit hook runs it too, and it runs first in both hooks. There is no override (the old `ALLOW_SECRET_SCAN`, the plaintext twin re-encryption and the `.enc` twin sync are gone).
+
+- Changed: the back-end skeleton (`hfs sync --init`) follows the unit standard. It writes no spec but `*.service.spec.ts` (the specs of the controller, config, errors, logging and composition are gone), the health door is thin (`LiveController` dispatches one `CheckLivenessQuery` on the injected query bus, `CheckLivenessHandler.process` is one `return this.liveness.check()`, the liveness logic lives in `domain/liveness/liveness.service.ts` with its spec at 100 percent), and the platform gains `clock` (the one reader of the ambient time), `composition` (`injector`), `cqrs` (`ICQRSHandler`, the bus decorators) and `logging` decorators and log events; role-suffixed file names (`env-source.config.ts`, `domain.error.ts`, `logging.log-events.ts`, `json-logger.service.ts`). A repository lists `@nestjs/cqrs` in its dependencies and `tslib` in its devDependencies; `@nestjs/terminus` is no longer needed by the skeleton.
+- Added: `hfs new service <dir> <name> [--inject ...]` and `hfs new spec <file>.service.ts` (`scaffold/service.mjs`): a back-end `*.service.ts` is created together with its `<name>.service.spec.ts` skeleton, built with `Test.createTestingModule({ providers }).compile()` and `moduleRef.get(Service)`. The constructor is read with the repository's TypeScript compiler API; each `@Inject*()` token and each class-typed parameter becomes one provider, its double chosen from `ruleParams.be.specDoubles` of the slot manifest (the table of the lint law `spec-infra-double-from-kit`), and every public method gets one placeholder `it`. The target must be owned by a slot; nothing is ever overwritten.
+- Changed: Sonar no longer depends on coverage (unit test standard rule 6). The managed `sonar-project.properties` drops `sonar.coverage.exclusions` and `sonar.javascript.lcov.reportPaths`, `knowledge/sonar-gate.yaml` has no coverage condition (the gate keeps duplication, blocker and critical issues, hotspots, and zero open imported issues), and the managed CI workflows drop the Codecov upload and its `id-token: write` permission. `codecov.yml` is no longer a managed file (slot `repo.quality-config` is `sonar-project.properties` only) and `sync` no longer asks the installed preset for `sonarCoverageExclusions`. The managed back-end `test` script is `jest --selectProjects unit --coverage` (fails below the per-file 100 threshold), and a new `test:affected` (`jest --selectProjects unit --passWithNoTests`, no coverage) is what the pre-commit and pre-push hooks run over related or changed specs, because a per-file threshold judged on a partial run would fail every service the run did not touch; the front-end `test:ci` runs `vitest run` without coverage.
+- Changed: a front end has no tests by standard (owner 2026-09-30). `hfs sync` no longer renders anything for a front-end test: no `vitest.config.ts`, `tsconfig.e2e.json`, `.github/workflows/e2e.yml` or `codecov.yml`; the front-end `package.json` scripts have no `test`, `test:ci`, `test:affected`, `typecheck:e2e` or `test:e2e`; the husky hooks and `ci.yml` run no test step and no codecov upload; `sonar-project.properties` carries no `sonar.tests`, `sonar.test.inclusions`, coverage exclusions or lcov path; the root `tsconfig.json` excludes only `node_modules`; `hfs sync --init` writes no spec and no vitest config; `loadPresets` needs no preset for a front end (`@starci/vitest-preset` and `@starci/playwright-preset` are deleted). Slots: `fe.e2e`, `fe.e2e-support` and the FE test roles are deleted, `fe.tool-config-repo` is `turbo.json` only, `codecov.yml` is a back-end slot (`be.codecov`). Added: `FE_NO_TESTS` (R97), the one front-end enforcer: any spec, e2e file, test directory, test-tool file, test script or test dependency is a finding, with no exception; R66 `FE_E2E_SHAPE` and R67 `FE_SPEC_QUALITY` are retired (rule ids increase and a retired id is never reused).
+
+- Changed: R47 `test-world-files` (`BE_TEST_TOPOLOGY`) judges the world against the repository's own stack: `fakes/<provider>/` may not fake a service `.starcistacks/<env>` declares (name, image repository or a well-known alias: postgres, redis, keycloak, a mail host, ...). One exception: a stateless GPU or external-model service that `src/tests/world/test-world.config.ts` (the test-world library's declaration; its `stacks` name the environments) declares in `fakedBy` with a non-empty `reason`; a stateful kind or a service with a persistent volume is never accepted, and a `fakedBy` entry naming a missing stack service or fake folder is refused. The stack reader is `scripts/lib/stack-services.mjs`.
+
+- Added: `hfs emit-contracts [--repo <dir>]` and the managed script `contract:emit`: writes `contracts/<app>/schema.graphql` of every api app that serves GraphQL as `printSchema(lexicographicSortSchema(schema))`. What an app serves is read from its source: the module graph is walked from `AppModule` of `apps/<app>/src/app.module.ts` through every import (imports of imports, `register`/`forRoot`/`forRootAsync` dynamic modules, `forwardRef`, spreads, both branches of a conditional), the `GraphQLModule` `include` list is honored, and an app whose graph holds no GraphQL server is skipped; only the resolver classes of the served modules are loaded, compiled the way `tsc` compiles them (decorator metadata comes from the type checker), and Nest's `GraphQLSchemaFactory` builds the schema, so it needs no environment, database or network and never boots the app. A dependency of a resolver that cannot load where the emit runs is stood in for and listed; a graph or option the reader cannot decide is an error naming the file. TypeScript, Nest and graphql are the repository's own. The rendered `.prettierignore` skips `contracts/`.
+- Added: `hfs emit-contracts` also writes `contracts/<app>/openapi.json` (OpenAPI 3.1) for an api app whose `apps/<app>/src/operations.ts` exports the typed operation table `OPERATIONS` (canon BE-OPERATIONS-1): one `POST /operations` route whose body and answer are a oneOf over the operations, each with `x-operation: "<name>@<version>"`, the input, the output and the Outcome (`ok` value or declared refusal code); the schemas are read from the TypeScript checker, sorted, deterministic, and `any`/`unknown`/`Record<string, unknown>`/unbound generics/`string` refusal codes are errors naming the operation. The full `hfs check` compares it with the committed file (R23), and an operation table without a committed `openapi.json` is a finding.
+- Changed: `hfs emit-contracts` folds only what literals decide: `if`/ternary/`&&`/`||`/`??` over the literal options an app passes (`register({ features })`, const-bound literals, spreads of consts, `list.push(...)`, early `return`) are followed to the branch they select; a condition it cannot decide (an env value, a call result, a parameter with no literal, an unknown list) is kept as an undecided choice and is an error, naming file, line and condition, unless every branch serves the same resolvers. Loops/switch/try that return or change a list, and objects or server options with an unknown spread, are errors.
+- Added: the full `hfs check` (never `--fast`, which says so in its coverage line) emits every back-end api app into a temp directory and compares its hash with the committed `contracts/<app>/schema.graphql`; a mismatch is `HFS_CONTRACT_SNAPSHOT_DRIFT` naming both shas and `npm run contract:emit`, and an emit that cannot run is the same code with the emit error.
+
+- Added: a front end's managed configuration, by the same mechanism as a back end (`fe.tool-config`, `fe.package-manifest`, forbidden `fe.tool-config-local`; `fe.thin-config` and the mixed `repo.package-manifest` are gone). `hfs sync` renders `tsconfig.json` (`@starci/tsconfig/next.json`), the one-line `eslint.config.mjs`, the one-line `stylelint.config.mjs` (`loadAppTokens(import.meta.url)`), `.prettierrc`, `.prettierignore` and the `scripts` block of `package.json` (`lint:check` = one ESLint run plus stylelint over `{apps,packages}/*/src/**/*.css`; `dev:<app>` and `start:<app>` per app). `turbo.json` is the repository's own (`fe.tool-config-repo`).
+- Changed: the front-end hooks and workflow: pre-commit runs eslint, stylelint and prettier on the staged files (no lint-staged), pre-push adds `format:check` and `hfs:check -- --fast`, CI runs `hfs:report`, `lint:check` (with stylelint), `format:check`, `typecheck` and `build`.
+- Changed: `hfs check` judges both profiles: `HFS_RULE_OFF_WITHOUT_REPLACEMENT` also for `stylelint.config.mjs`, `HFS_TS_STRICT` for the front end's root tsconfig, `HFS_TOOL_CONFIG_LOCAL` also for a stylelint plugin, stylelint flags and a tool configuration key of a `package.json`.
+- Changed: one converter for both linters, `hfs report <eslint|stylelint> <in> <out>`; `hfs report-stylelint` is removed and `sonar.eslint.reportPaths` is no longer rendered (Sonar's own ESLint import drops issues on files outside `sonar.sources`). ESLint and stylelint findings on a file Sonar does not index are filed on the first source file with the real path in the message, like the HFS findings. `sonar.externalIssuesReportPaths` lists `reports/{hfs,eslint,stylelint}.sonar.json`; a front end's `sonar.sources` and `sonar.tests` include `packages` when hfs.json opts into a package slot, and its `sonar.typescript.tsconfigPaths` gains `packages/*/tsconfig.json`.
+- Changed: the front-end skeleton (`hfs sync --init`): a one-app repository keeps its next-intl stack and its one API client in the app; a repository with two or more apps writes them once as `packages/<project>-i18n` (`createAppI18n`, `./proxy`, `./request`) and `packages/<project>-api` (`request`, `Outcome`) and keeps thin adapters in each app, and `--init` refuses it unless hfs.json opts into `fe.package.i18n` and `fe.package.api`. Every app also gets a `vitest.config.ts`; the shell reads `modules/i18n` through its index.
+- Changed: the machine no longer treats a `lint:e2e` command as running e2e (linting is not running), and its root-entry allowlist accepts `stylelint.config.mjs`.
+
+- Changed: `hfs check` runs the whole architecture machine after its slot, pin and size checks. Its violations and errors are findings under the machine's own rule ids, each with the Vietnamese why of its code, and any of them exits 1. The package carries a byte copy of the machine and every file it imports, plus the failure-code slice of every code the machine can emit. The machine loads `typescript` from the checked repository; a repository without it fails with `ARCH_TYPESCRIPT_MISSING`.
+- Added: `hfs check --fast [--base <ref>]`, the flag the template pre-push hook already called. It judges the owners changed since the merge-base with `origin/main` (else `main`), skipping clones, dead exports and the file-system tree checks. With no merge-base it is a refusal (exit 2) that names the fix.
+- Added: `HFS_EMPTY_DIR`, `HFS_GHOST_TREE` (an empty directory beside a sibling within two edits of its name) and `HFS_UNTRACKED_ROOT_ENTRY` (entries git neither tracks nor ignores, outside an `ignored` slot): rule R03 ships as an `hfs` enforcer.
+- Changed: the machine's root-entry allowlist accepts `.prettierignore`, which the slot manifest already requires.
+- Changed: one code per finding. `HFS_PATH_NO_SLOT` is `HFS_SLOT_UNDECLARED` and `HFS_REQUIRED_MISSING` is `HFS_SLOT_REQUIRED_MISSING` (the rule catalog's names); `HFS_STACKS_PLAINTEXT` of `hfs work-hygiene` is `HFS_PLAINTEXT_SECRET`. The old names are gone.
+- Added: the owed `hfs` enforcers ship, each with a violating and a passing spec: `HFS_PLAINTEXT_SECRET` (R06), `HFS_STACKS_SHAPE` (R10), `HFS_CI_MISSING_CANON` (R13), `HFS_DEP_VERSION_SKEW` (R14), `HFS_CONTRACT_SNAPSHOT_DRIFT` (R23), `BE_TEST_TOPOLOGY` (R47), `FE_WIRE_GENERATED` (R52), `FE_I18N_PLACEMENT` (R59) and `FE_I18N_CATALOG` (R60) in `hfs check`; `HFS_GITIGNORE_BLOCK_DRIFT` (R04) and `HFS_SONAR_CONFIG` (R11) by comparing the file with its render; `HFS_FORMAT` (R19) by running the repository's own prettier (not under `--fast`; a repository without prettier is a refusal, `HFS_FORMAT_TOOL_MISSING`).
+- Changed: a plaintext secret file the slot manifest forbids (`.env`, `*.pem`, ...) is one `HFS_PLAINTEXT_SECRET` finding, no longer also `HFS_FORBIDDEN_PRESENT`.
+- Changed: the rendered `sonar-project.properties` carries no `sonar.host.url` (the host comes from the CI variable and the stack declaration).
+- Changed: `hfs check` needs the repository's installed jest / vitest preset (the coverage exclusions of the render) and prettier; without either it refuses (exit 2) instead of skipping the check.
+- Changed: owner test layout 2026-09-30. The tests' own `src/tests/tsconfig.json` (extends the root config and `@starci/tsconfig/e2e.json`) replaces `src/tests/e2e/tsconfig.json`; the managed root `tsconfig.json` excludes `src/tests/world`, `integration`, `e2e` and `contract` (fixtures stay in the root program). Scripts `test:integration`, `test:e2e`, `test:contract` (each `npm run typecheck:tests && jest --selectProjects <name>`) and `typecheck:tests` replace `typecheck:e2e` and `test:e2e:live`. `HFS_E2E_IN_AUTOMATIC_GATE` keeps integration, e2e and contract out of hooks, coverage and automatic CI. A slot forbids the retired `src/tests/e2e/world/` (goes to `src/tests/world/`); a spec whose suffix disagrees with its folder matches no slot.
+
+- Added: `hfs sync` renders a back end's whole tool configuration from templates and `hfs check` compares it. The managed files are the slots of `slots.yaml` that name `managedBy` (each lists literal files; `managedBy` names the template directory `templates/<profile|common>/<managedBy>/`): `tsconfig.json` (extends `@starci/tsconfig/be.json`, adds the three aliases), `tsconfig.build.json`, `src/tests/tsconfig.json`, the one-line `eslint.config.mjs`, `jest.config.js`, `.prettierrc`, `.prettierignore`, and the `scripts` block of `package.json` (`lint`, `lint:check`, `typecheck`, `typecheck:tests`, `test`, `test:integration`, `test:e2e`, `test:contract`, `format`, `format:check`, `hfs:check`, `build`, one `start:<app>` per runnable app and `migrate`), compared as parsed JSON. Only the `.gitignore` block and `.starciwork/.gitignore` remain listed in code.
+- Added: `hfs check` reports `HFS_MANAGED_FILE_DRIFT` (R05), `HFS_RULE_OFF_WITHOUT_REPLACEMENT` (R17, the eslint one-liner), `HFS_TOOL_CONFIG_LOCAL` (R16, tool configs outside the managed set, local rule files, flags that swap the configuration) and `HFS_TS_STRICT` (R22, by flag). The bundle no longer holds the templates; the check that renders them lives in `sync/`.
+- Changed: the back-end hooks and workflows call only managed scripts: pre-commit runs `eslint` and `prettier --check` on the staged files instead of lint-staged, CI runs `npm run hfs:check` (the second `hfs sync --check` step is gone), `format:check` and `npm test -- --coverage --ci`; pre-push adds `format:check`. The front-end templates lose the `hfs sync --check` CI step.
+- Changed: templates moved under `templates/<profile|common>/<managedBy>/`; `validateHfs` compares `hfs` with the manifest major (it wrongly demanded 2); a back-end app needs a `kind`.
+- Changed: the machine's root-entry allowlist accepts `.prettierrc`.
+- Changed: slots. `be.tool-config` (managed), `be.tool-config-local` (forbidden), `be.package-manifest`, `be.lockfile`, `be.nest-cli` and `fe.thin-config` replace the mixed `repo.tool-config` and `repo.package-manifest`; `repo.tool-config` keeps `.editorconfig` and `.nvmrc`. `.sops.yaml` no longer claims a `managedBy` nothing renders.
+
+- Added: one Sonar mechanism for back ends and front ends. `hfs check --sonar <file>` writes the error findings as a Sonar Generic Issue Import document (engine `starci-hfs`, rule id = the finding code, catalog English and Vietnamese text, deterministic), and `hfs report-stylelint <in> <out>` converts stylelint's json output into the same format (`report/sonar.mjs`). The managed `sonar-project.properties` sets `sonar.eslint.reportPaths` and `sonar.externalIssuesReportPaths` and no longer sets `sonar.host.url` (R11); the managed CI workflows produce `reports/eslint.json`, `reports/hfs.sonar.json` (and the stylelint reports for a front end) and run the Sonar scan and gate with `!cancelled()`; a back end's scripts gain `lint:report` and `hfs:report`; `reports/` is an ignored slot.
+- Added: `HFS_SONAR_CONFIG` (R11) ships as an `hfs` enforcer: `sonar-project.properties` differs from its render, or the stack declaration names another quality gate than the bundled `knowledge/sonar-gate.yaml`. The R20 and R21 Sonar enforcers ship as conditions of that gate file (`overall`: 0 open issues, duplicated lines density, S3776).
+- Changed: every finding of `hfs check --json` carries the catalog's English `title` beside `titleVi`.
+
 ## 1.0.1 - 2026-09-30
 
 - Fixed: `package.json` now has `exports` for `./runtime/*` and `./package.json`, so other published packages can resolve the runtime copy it carries (`@starci/hfs/runtime/knowledge/hfs/slots.yaml`, `@starci/hfs/runtime/engine/yaml.mjs`) with `import.meta.resolve` or `require.resolve`, wherever the package is installed. `@starci/eslint-canon-be` 1.7.1 reads the slot manifest this way.

package/README.md

@@ -2,41 +2,139 @@
 
 The HFS command line of a StarCi product repository. It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
 and it is self-contained: `runtime/` carries the slot manifest, the canon pins, the Vietnamese why
-catalog slice and the loader, so it runs where there is no runtime checkout.
+catalog slice, the loader and the architecture machine with every file it imports, so it runs where there is no runtime
+checkout. The machine loads `typescript` from the repository it checks (never its own copy), so run `npm ci` first.
 
 ```sh
-npx hfs check   [--repo <dir>] [--json]       # exit 1 on any error-level finding
+npx hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>] [--sonar <file>]   # exit 1 on any error-level finding
+npx hfs report <eslint|stylelint> <in> <out> [--repo <dir>]   # a linter's json -> Sonar Generic Issue Import (see Sonar)
 npx hfs init    [--repo <dir>] [--stdout]     # write a starter hfs.json (never overwrites); --stdout only prints
+npx hfs emit-contracts [--repo <dir>]         # write contracts/<app>/schema.graphql of every api app that serves GraphQL and contracts/<app>/openapi.json of every api app with a typed operation table (the managed script contract:emit)
 npx hfs explain <path> [--repo <dir>] [--json]
-npx hfs sync (--check | --write) [--root <dir>]   # generated files: husky, CI, .gitignore block, sonar, codecov (sync/, templates/)
-npx hfs work-hygiene                              # pre-commit guard for staged .starciwork / .starcistacks paths
+npx hfs sync (--check | --write) [--root <dir>]   # generated files: the managedBy slots of slots.yaml, the .gitignore block (sync/, templates/)
+npx hfs work-hygiene                              # pre-commit guard: staged .starciwork / .starcistacks paths, and the secrets guard over every staged file (read from the index)
+npx hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]   # a back-end service and its unit spec skeleton
+npx hfs new spec <file>.service.ts [--repo <dir>]                                                              # the spec skeleton of an existing service
 ```
 
-`hfs check` reads the repository's `hfs.json` and the tracked paths (`git ls-files`), and reports, each with a why code and its
-Vietnamese text (`modules/kernel/failure-codes.yaml`):
+## Creating a service
+
+Only `*.service.ts` files are unit-tested (unit test standard), each with exactly one colocated `<name>.service.spec.ts`. `hfs new` is the one way they come into being together:
+
+- `hfs new service src/modules/domain/commission commission --inject InjectPrimaryEntityManager=@modules/platform/database:EntityManager --inject InjectClock=@modules/platform/clock:Clock` writes `commission.service.ts` (the class, `@Injectable()`, the constructor with the given `@Inject*()` parameters) and `commission.service.spec.ts`. `--inject` is `<Decorator>=<module>:<Type>` for a custom `@Inject*()` decorator (its token is the UPPER_SNAKE of the name, `PRIMARY_ENTITY_MANAGER`, exported from the same module) or `<Class>=<module>` for a class-typed dependency. The directory must belong to a slot of the manifest that owns the file (a service lives in `src/modules/{domain,platform,integrations}/<capability>/`), and `hfs new` never overwrites.
+- `hfs new spec src/modules/domain/member/member-profile.service.ts` writes only the spec of a service you wrote by hand. It reads the constructor with the repository's own TypeScript compiler API, so `npm ci` comes first.
+
+The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `OUTBOX` -> `recordingOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
+
+`hfs check` reads the repository's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree, and then runs the
+whole architecture machine over the repository. Every finding carries a why code and its Vietnamese text
+(`modules/kernel/failure-codes.yaml`).
+
+Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `hfs check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
 
 | Code | Level | Meaning |
 |---|---|---|
-| `HFS_PATH_NO_SLOT` | error | a tracked path no slot owns (the nearest slot is named) |
+| `HFS_SLOT_UNDECLARED` | error | a tracked path no slot owns (the nearest slot is named) |
 | `HFS_SLOT_NOT_ENABLED` | error | a path in an opt-in slot `hfs.json` did not declare |
 | `HFS_SLOT_AMBIGUOUS` | error | two slots own the path equally (a manifest gap) |
 | `HFS_TRACKED_MUST_BE_IGNORED` | error | a tracked path in an `ignored` slot (build output, generated) |
 | `HFS_FORBIDDEN_PRESENT` | error | a tracked path in a forbidden / `external` slot |
-| `HFS_REQUIRED_MISSING` | error | a file or directory a required slot, app or instance must contain |
+| `HFS_SLOT_REQUIRED_MISSING` | error | a file or directory a required slot, app or instance must contain |
 | `HFS_MIN_INSTANCES` | error | fewer instances of a slot than `minInstances` |
 | `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |
 | `HFS_SIZE_SOFT_BACKLOG` | info | a source file over `ruleParams.fileLines.soft`; report only, never fails |
+| `HFS_MANAGED_FILE_DRIFT` | error | a managed file that exists but differs from its render (hooks, workflows, sonar, `tsconfig.build.json`, `src/tests/tsconfig.json` (back end), `jest.config.js` (back end), `.prettierrc`, `.prettierignore`, the `scripts` block of `package.json`, compared as parsed JSON) |
+| `HFS_RULE_OFF_WITHOUT_REPLACEMENT` | error | `eslint.config.mjs`, or a front end's `stylelint.config.mjs`, differs from its one-line render, so a rule could be off, warned or redefined in it |
+| `HFS_TOOL_CONFIG_LOCAL` | error | a repository holds a tool config outside the managed set (`.eslintrc*`, `.eslintignore`, a second `eslint.config.*` or `stylelint.config.*`, another prettier or lint-staged config, or a jest config in a back end that is not the one root file), a file that defines an ESLint rule or a stylelint plugin, a tool configuration key in a `package.json` (`eslintConfig`, `stylelint`, `prettier`, `lint-staged`, `jest`), or a script that runs eslint, stylelint or prettier with a flag that swaps the configuration |
+| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render (no host URL; the ESLint report and HFS import paths), or the stack declaration names another quality gate than the one of `knowledge/sonar-gate.yaml` |
+| `HFS_TS_STRICT` | error | the root `tsconfig.json` sets, lowers or adds anything but `extends` the preset (`be.json`, `next.json`), the template's `exclude` and (back end) the three `paths`; the finding names the flag |
+| `HFS_EMPTY_DIR` | error | a directory with no file below it (git tracks none), outside `.git`, `node_modules` and `ignored` slots; the topmost one is reported |
+| `HFS_GHOST_TREE` | error | an empty directory beside a sibling whose name is within two edits of its own (`business` / `bussiness`) |
+| `HFS_UNTRACKED_ROOT_ENTRY` | error | an entry git neither tracks nor ignores (`git ls-files -o --exclude-standard`), outside an `ignored` slot |
+| `HFS_PLAINTEXT_SECRET` | error | a tracked plaintext secret: an env, key or credentials file, a value the push scan refuses (never printed), or an `.enc` that is no sops envelope (R06) |
+| `HFS_STACKS_SHAPE` | error | a `.starcistacks` path outside the standard shape (a sealed file outside `<env>/secrets/`, `runtime/files/`, root `DESIGN.md` or `k8s/`), a local Sonar not owned by the host, a service still rooted at `.stacks` (R10) |
+| `HFS_CI_MISSING_CANON` | error | `ci.yml` without a `run: npx hfs check` step (whole check, pinned version), or `.husky/pre-push` without `npm run typecheck` and `npm run lint:check` (R13) |
+| `HFS_DEP_VERSION_SKEW` | error | a dependency at two specs across the root and workspace `package.json` files, a dependency declared at another version than the root `overrides` pin, or a nested copy of a declared dependency in `package-lock.json` (R14) |
+| `HFS_CONTRACT_SNAPSHOT_DRIFT` | error / info | a back end serving GraphQL without `contracts/<app>/schema.graphql`, a front-end contract copy that differs by hash from the sibling back end named by `hfs.json` `stacks` (info when the sibling is not checked out) (R23) |
+| `BE_TEST_TOPOLOGY` | error | a `*.test.*` file, a `testing/` folder, a second jest configuration or a `jest` key in `package.json` (R47; `int-spec`, `harness-spec` and the retired test folders are the machine's `HFS_TEST_KIND_RETIRED`) |
+| `BE_SPEC_PLACEMENT` | error | a `*.spec.*`, `*.test.*` or `*-spec.*` file outside the four test layers, `scripts/` and `tools/` included (R102) |
+| `HFS_REPO_LOCAL_CHECK` | error | a `check-*` file in `scripts/` or `tools/`, an `eslint-local-rules*` file or local eslint plugin, or a script that runs a local check (R103) |
+| `HFS_LINT_SUPPRESSION_FILE` | error | an `eslint.suppressions*` file, a `lint:suppressions` script, an eslint suppress flag or a suppressions config (R104) |
+| `HFS_PROOF_COMMAND_FILE_MISSING` | error | a `.starciwork` `requiresProof.<kind>.command` that runs a file the repository does not hold (R105) |
+| `FE_WIRE_GENERATED` | error | a contract copy with no `codegen` script wired before `build` and `typecheck`, or generated types older than the copy (R52) |
+| `FE_I18N_PLACEMENT` | error | no `next-intl`, no `src/proxy.ts`, a `middleware.ts`, a route file outside `[locale]`, no `vi.json` catalog (R59) |
+| `FE_I18N_CATALOG` | error | a locale catalog lacking a key another locale has (R60) |
+| `FE_I18N_KEYS` | error | a literal key read through `next-intl` that a locale lacks, or a catalog key no source reads (R106; the architecture machine) |
+| `FE_NO_TESTS` | error | a front end holds a `*.spec.*`, `*.test.*` or `*-spec.*` file, an `e2e/`, `__tests__/`, `__mocks__/` or `test-support/` directory, a vitest, Playwright, jest or Cypress file, a test script, or a test dependency in a `package.json`; no exception (R97; `scripts/lib/hfs-rules/fe-no-tests.mjs`) |
+| `HFS_GITIGNORE_BLOCK_DRIFT` | error | the managed `.gitignore` block differs from its render (R04; `sync/managed.mjs`) |
+| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, no coverage import (R11; `sync/managed.mjs`) |
+| `HFS_FORMAT` | error | a tracked file the repository's own prettier would change (R19; `sync/format.mjs`, not under `--fast`) |
+| `HFS_FORMAT_TOOL_MISSING` | refusal (exit 2) | prettier is not installed in the repository; the format check is never skipped |
 
-Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag). The command never writes to the repository
+The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
+files is the `managedBy` slots of `slots.yaml`; `hfs sync --write` renders them and `hfs check` compares them, so a hand edit and a forgotten `sync` are the same finding.
+Each finding is reported once: the eslint and stylelint one-liners under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
+A front end is rendered by the same mechanism as a back end: `tsconfig.json`, `eslint.config.mjs`, `stylelint.config.mjs`, `.prettierrc`, `.prettierignore`, the hooks, the workflow, the Sonar file
+and the `scripts` block (`lint:check` is the one lint gate, ESLint over the repository plus stylelint; a front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool, test script or test dependency, `scripts/` included). `turbo.json` stays the repository's own
+(`fe.tool-config-repo`): it carries the repository's task graph, which no preset can render.
+
+The architecture machine (`scripts/checks/architecture.mjs` of the runtime, the same code bundled here): tiers and import
+direction, owner public API, cycles, module registration and composition, clones, dead exports, required files, size growth,
+the source-shape, contract-form and front-end rules, and the repository-tree rules. Each violation and each error is one
+finding under the machine's own rule id (`BE_TIER_DIRECTION`, `HFS_UNUSED_EXPORT`, `ARCH_OWNER_EXPORT_BYPASS`, ...). A
+repository without `typescript` installed fails with `ARCH_TYPESCRIPT_MISSING`; the check never passes because it could not run.
+
+`--fast` (the template pre-push hook runs `npx hfs check --fast`) judges only what changed since the merge-base of `HEAD` with
+`origin/main` (else `main`; `--base <ref>` names another ref): the slot and pin checks on the changed paths, the machine on the owners
+of the changed source files without clones and dead exports, and no file-system tree checks. The required-file and minimum-instance
+checks still cover the whole tree. With no merge-base `--fast` is a refusal (exit 2) that names the fix, never a silent full
+pass. Without `--fast`, `--base <ref>` is the base of the size-growth check.
+
+Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). The command never writes to the repository
 except `hfs init`, which writes `hfs.json` only when none exists.
 
+## Sonar
+
+One mechanism, the same for a back end and a front end: every finding of the canon is imported into Sonar, and the quality gate
+fails while any is open. Nothing is configured per repository; the pieces are managed files (`hfs sync`) and this package.
+
+| Source | Report | How Sonar reads it |
+|---|---|---|
+| `hfs check` (repository, managed-file and architecture-machine findings) | `reports/hfs.sonar.json`, from `hfs check --sonar reports/hfs.sonar.json` | `sonar.externalIssuesReportPaths`, engine `starci-hfs`, rule id = the finding code |
+| ESLint (the BE and FE canon plugins alike) | `reports/eslint.json` (`npm run lint:report`) then `reports/eslint.sonar.json`, from `hfs report eslint reports/eslint.json reports/eslint.sonar.json` | `sonar.externalIssuesReportPaths`, engine `eslint`, rule id = the ESLint rule |
+| stylelint (front end) | `reports/stylelint.json` (`npm run lint:report:css`) then `reports/stylelint.sonar.json`, from `hfs report stylelint ...` | `sonar.externalIssuesReportPaths`, engine `stylelint`, rule id = the stylelint rule |
+
+`--sonar` writes the error findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
+failing check still leaves its report. A rule's name and description are the catalog's English title and Vietnamese title, meaning and next step;
+impacts are HIGH (maintainability). `info` findings (the soft-size backlog) are report-only and not imported. The output is sorted, so two runs
+over one tree are byte-identical. Sonar drops an issue on a file it does not index (a tracked source file or stylesheet under `sonar.sources`), so the ONE placement rule of the three engines files a finding on
+any other path (hfs.json, a workflow, a config file, `e2e/`, a package the sources do not list) and a finding with no path on the first source file, its message starting with the real path.
+Sonar's own ESLint import (`sonar.eslint.reportPaths`) is not used: it drops those issues silently. A front end's `sonar.sources` and `sonar.tests` are `apps`, plus `packages` when hfs.json opts into `repo.packages` or an `fe.package.*` slot.
+
+The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths` (`reports/hfs.sonar.json`, `reports/eslint.sonar.json` and, for a front end, `reports/stylelint.sonar.json`) and no `sonar.host.url` (the host is
+`SONAR_HOST_URL`); the managed CI workflow produces the reports and runs the scan and the gate action with `!cancelled()`, so a failed check step still
+reaches Sonar while the job stays failed. There is no `continue-on-error`. Both profiles run `npm run hfs:report`, `npm run lint:report` (a front end also `npm run lint:report:css`) and `npx hfs report <linter> <in> <out>` for each. The duplicate-block threshold (`ruleParams.<profile>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
+clones with its own token rule), so the machine enforces it (R21) and its findings are imported like every other.
+
+The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (duplication, blocker and critical issues, hotspots; no coverage condition) and an `overall` part (0 open issues on the whole code,
+duplicated lines density, cognitive complexity through the S3776 rule). A SonarQube gate condition cannot filter by engine, so the condition counts every
+open issue, imported or native; that is stricter than the three imports alone and is intended. `hfs check` reports `HFS_SONAR_CONFIG` (R11) when the
+properties file is not its render or the stack declaration names another gate. R20 and R21 have their Sonar enforcers as conditions of that file.
+
+Sonar does not depend on coverage: the managed properties file has no `sonar.*.lcov.reportPaths` and no `sonar.coverage.*`, the gate has no coverage condition, and the managed CI workflow uploads no coverage anywhere (no Codecov). A back end's unit coverage is the runner's: the managed `test` script is `jest --selectProjects unit --coverage`, which fails below the per-file 100 threshold on `src/**/*.service.ts`.
+
 ## Maintaining the bundle
 
-`runtime/` is a byte copy of the runtime files listed in `scripts/sync-runtime.mjs` (plus the catalog slice of the codes the
-check can emit). After changing `scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-slots.mjs`, `knowledge/hfs/slots.yaml`,
-`knowledge/hfs/canon-pins.yaml` or the catalog entries of those codes, run `node packages/hfs/scripts/sync-runtime.mjs`;
+`runtime/` is a byte copy of the slot loader files, the pins, and the import closure of `scripts/lib/hfs-check.mjs` and
+`scripts/checks/architecture.mjs` (computed by `scripts/sync-runtime.mjs`, so a new import of the machine is bundled without
+editing a list), plus the catalog slice of every code `hfs check` can emit: its own and the machine's (`ARCHITECTURE_RULE_IDS`,
+derived from the machine's rule id lists). After changing any of those files, `knowledge/hfs/slots.yaml`,
+`knowledge/hfs/canon-pins.yaml`, `knowledge/patterns/fe/folder.yaml` or the catalog entries of those codes, run `node packages/hfs/scripts/sync-runtime.mjs`;
 `tests/hfs-cli.spec.mjs` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
+The examples gate `node scripts/checks/check-example-architecture.mjs` runs this CLI (full check) on every `examples/*` directory
+with an `hfs.json` and fails on any error-level finding (it is heavy: run it once, by hand).
+
 ## Serving knowledge to other packages
 
 `package.json` `exports` opens `./runtime/*`, so a package that needs a runtime file resolves it from the installed copy

package/bin/hfs.mjs

@@ -1,35 +1,76 @@
 #!/usr/bin/env node
 // hfs - the HFS command line of a StarCi product repository.
-//   hfs check   [--repo <dir>] [--json]     every tracked path has a slot; required files exist; nothing forbidden or
-//                                            tracked-that-must-be-ignored; pins match; soft-size backlog (report only).
-//                                            Exit 1 on any error-level finding.
+//   hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>] [--sonar <file>]
+//                                            every tracked path has a slot; required files exist; nothing forbidden or
+//                                            tracked-that-must-be-ignored; pins match; every managed file equals its render
+//                                            (sync/managed.mjs, the .gitignore block and sonar-project.properties included); no empty or ghost
+//                                            directory, no untracked entry outside an ignored slot; plaintext secrets, the .starcistacks shape, CI
+//                                            and pre-push canon steps, dependency version skew, the contract snapshot and the test, wire and i18n
+//                                            trees; prettier over every tracked file through the repository's own install (sync/format.mjs; not under
+//                                            --fast, and a repository without prettier is a refusal); soft-size backlog (report only); then the whole
+//                                            architecture machine (tiers, owners, clones, dead exports, module registration, the
+//                                            front-end and back-end source rules), each violation a finding with its why.
+//                                            --fast: only what changed since the merge-base with origin/main (else main; --base
+//                                            overrides it, and without --fast is the base of the size-growth check); the machine
+//                                            runs on those owners without clones and dead exports. No merge-base is a refusal
+//                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding.
+//                                            --sonar: also write the error findings as a Sonar Generic Issue Import file (report/sonar.mjs),
+//                                            before the verdict, so a failing check still leaves the report Sonar imports.
+//   hfs report <eslint|stylelint> <in> <out> [--repo <dir>]  convert a linter's json output into a Sonar Generic Issue Import file
+//                                            (one converter for both linters; a finding on a file Sonar does not index is filed on the first
+//                                            source file of sonar.sources, the real path in its message).
 //   hfs init    [--repo <dir>] [--stdout]   write a starter hfs.json by detecting the profile and the apps.
 //   hfs explain <path> [--repo <dir>] [--json]   which slot owns the path, its tier, allowed imports, required tests.
-//   hfs sync (--check | --write) [--root <dir>]  the generated files (husky, CI, .gitignore block, sonar, codecov); sync/cli.mjs
-//   hfs work-hygiene                              the pre-commit guard for staged .starciwork and .starcistacks paths; sync/cli.mjs
+//   hfs emit-contracts [--repo <dir>]      write contracts/<app>/schema.graphql of every api app that serves GraphQL (emit/contracts.mjs):
+//                                            printSchema(lexicographicSortSchema) of the resolvers the app root composes; no env, no database, no network.
+//   hfs sync (--check | --write) [--root <dir>]  the generated files (husky, CI, .gitignore block, sonar); sync/cli.mjs
+//   hfs work-hygiene                              the pre-commit guard: staged .starciwork and .starcistacks paths, and the secrets guard over every staged file (read from the index); sync/cli.mjs
+//   hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
+//                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs): the spec is built
+//                                            with Test.createTestingModule, one provider per constructor dependency (kit doubles from @starci/jest-preset),
+//                                            one placeholder it per public method. Never overwrites a file.
+//   hfs new spec <file>.service.ts [--repo <dir>]  the spec skeleton of an existing service, read from its constructor with the repository's TypeScript
 // Every finding names a why code and carries its Vietnamese text. The command reads the repository, never writes to it
 // (init writes hfs.json only, and only when none exists). Exit codes: 0 clean, 1 error findings, 2 a refusal or bad usage.
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { checkRepo, explainPath, initRepo } from '../runtime/scripts/lib/hfs-check.mjs';
+import { checkRepository, explainPath, initRepo, trackedFiles } from '../runtime/scripts/lib/hfs-check.mjs';
 import { HfsSlotsError } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { formatFindings } from '../sync/format.mjs';
 import { main as syncMain } from '../sync/cli.mjs';
+import { SyncError } from '../sync/index.mjs';
+import { managedFindings } from '../sync/managed.mjs';
+import { emitContracts } from '../emit/contracts.mjs';
+import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
+import { contractEmitFindings } from '../runtime/scripts/lib/hfs-rules/contract.mjs';
+import { LINTER_KINDS, convertReportFile, sonarReport, sourceRootsOf, writeReport } from '../report/sonar.mjs';
 
-const USAGE = `hfs check [--repo <dir>] [--json]
+const USAGE = `hfs check [--repo <dir>] [--json] [--fast] [--base <ref>] [--sonar <file>]
+hfs report <eslint|stylelint> <in> <out> [--repo <dir>]
 hfs init [--repo <dir>] [--stdout]
+hfs emit-contracts [--repo <dir>]
 hfs explain <path> [--repo <dir>] [--json]
 hfs sync (--check | --write) [--root <dir>]
 hfs work-hygiene
+hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
+hfs new spec <file>.service.ts [--repo <dir>]
 `;
 const PER_CODE_LIMIT = 25;
-const VALUE_FLAGS = new Set(['--repo']);
-const BOOL_FLAGS = new Set(['--json', '--stdout']);
+const VALUE_FLAGS = new Set(['--repo', '--base', '--sonar', '--inject']);
+/** Flags that may repeat: their values are collected in order. */
+const LIST_FLAGS = new Set(['--inject']);
+const BOOL_FLAGS = new Set(['--json', '--stdout', '--fast']);
 
 function parse(argv) {
   const opts = { positional: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    if (VALUE_FLAGS.has(arg)) { opts[arg.slice(2)] = argv[i + 1]; i += 1; if (opts[arg.slice(2)] === undefined) throw new Error(`${arg} needs a value`); }
+    if (VALUE_FLAGS.has(arg)) {
+      if (argv[i + 1] === undefined) throw new Error(`${arg} needs a value`);
+      opts[arg.slice(2)] = LIST_FLAGS.has(arg) ? [...(opts[arg.slice(2)] ?? []), argv[i + 1]] : argv[i + 1];
+      i += 1;
+    }
     else if (BOOL_FLAGS.has(arg)) opts[arg.slice(2)] = true;
     else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}`);
     else opts.positional.push(arg);
@@ -39,7 +80,11 @@ function parse(argv) {
 
 function printCheck(result, out) {
   const { counts } = result;
-  out(`hfs check ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)\n`);
+  out(`hfs check${result.fast ? ' --fast' : ''} ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)\n`);
+  if (result.fast) out(`  ${result.fast.changed} path${result.fast.changed === 1 ? '' : 's'} changed since ${result.fast.base.slice(0, 12)}\n`);
+  out(`  architecture machine: ${result.machine.status === 'ran' ? `ran over ${result.machine.files} source files${result.machine.paths ? ` (owners ${result.machine.paths.join(', ')})` : ''}` : `skipped, ${result.machine.reason}`}\n`);
+  if (result.contracts) out(`  contract snapshots: ${result.contracts.status === 'checked' ? `emitted and compared, ${result.contracts.apps.map((a) => `${a.app}/${a.artifact} ${a.status}`).join(', ') || 'no api app'}` : `skipped, ${result.contracts.reason}`}
+`);
   const byCode = new Map();
   for (const f of result.findings) byCode.set(f.code, [...(byCode.get(f.code) ?? []), f]);
   for (const [code, list] of byCode) {
@@ -51,6 +96,13 @@ function printCheck(result, out) {
   out(`\n${counts.error} error finding${counts.error === 1 ? '' : 's'}, ${counts.info} report-only\n`);
 }
 
+/** The check's error findings as the Sonar import file: findings outside `sonar.sources` are filed on the first source file. */
+function writeSonarReport({ repoRoot, file, result }) {
+  let properties = '';
+  try { properties = fs.readFileSync(path.join(repoRoot, 'sonar-project.properties'), 'utf8'); } catch { /* no properties: every finding keeps its own path */ }
+  writeReport(file, sonarReport(result.findings, { sourceRoots: sourceRootsOf(properties), tracked: trackedFiles(repoRoot) }));
+}
+
 function printExplain(e, out) {
   out(`${e.path}\n`);
   if (e.status === 'no-slot') {
@@ -68,19 +120,71 @@ function printExplain(e, out) {
   if (e.code) out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
 }
 
-export async function main(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s) } = {}) {
+/** `presets` and `prettier` are test seams: the Sonar exclusions sync would load from the repository's installed preset, and the repository's own prettier. */
+export async function main(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier } = {}) {
   const [verb, ...rest] = argv;
-  if (!['check', 'init', 'explain', 'sync', 'work-hygiene'].includes(verb)) { stderr(USAGE); return 2; }
+  if (!['check', 'init', 'explain', 'sync', 'work-hygiene', 'report', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
   try {
     if (verb === 'sync' || verb === 'work-hygiene') return await syncMain(argv);
     const opts = parse(rest);
     const repoRoot = path.resolve(opts.repo ?? process.cwd());
     if (verb === 'check') {
       if (opts.positional.length) throw new Error('hfs check takes no path');
-      const result = checkRepo({ repoRoot });
+      const tracked = trackedFiles(repoRoot);
+      // Managed files, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier through the repository's own install (R19, never under --fast).
+      const extraFindings = [...await managedFindings({ repoRoot, tracked, presets }), ...(opts.fast === true ? [] : await formatFindings({ repoRoot, files: tracked, prettier }))];
+      // R23 against the app itself (full pass only): the committed snapshots equal what `emit-contracts` writes now.
+      let contracts = null;
+      let declared = null;
+      try { declared = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8')); } catch { /* checkRepository reports the unreadable declaration */ }
+      if (declared?.profile === 'be') {
+        if (opts.fast === true) contracts = { status: 'skipped', reason: '--fast does not emit the apps' };
+        else {
+          const emitted = contractEmitFindings({ repoRoot, files: tracked, repo: declared, emit: emitContracts });
+          extraFindings.push(...emitted.findings);
+          contracts = { status: 'checked', apps: emitted.apps };
+        }
+      }
+      const result = checkRepository({ repoRoot, fast: opts.fast === true, base: opts.base, extraFindings });
+      if (contracts) result.contracts = contracts;
+      if (opts.sonar !== undefined) writeSonarReport({ repoRoot, file: path.resolve(opts.sonar), result });
       if (opts.json) stdout(`${JSON.stringify(result, null, 2)}\n`); else printCheck(result, stdout);
       return result.ok ? 0 : 1;
     }
+    if (verb === 'report') {
+      if (opts.positional.length !== 3 || !LINTER_KINDS.includes(opts.positional[0])) throw new Error(`hfs report takes a linter (${LINTER_KINDS.join(' or ')}), an input and an output file`);
+      const [kind, input, output] = opts.positional;
+      let properties = '';
+      try { properties = fs.readFileSync(path.join(repoRoot, 'sonar-project.properties'), 'utf8'); } catch { /* no properties: every finding keeps its own path */ }
+      const sourceRoots = sourceRootsOf(properties);
+      const issues = convertReportFile({ kind, input: path.resolve(input), output: path.resolve(output), root: repoRoot, sourceRoots, tracked: sourceRoots.length ? trackedFiles(repoRoot) : [] });
+      stdout(`hfs report ${kind}: ${issues} issue${issues === 1 ? '' : 's'} written to ${output}\n`);
+      return 0;
+    }
+    if (verb === 'emit-contracts') {
+      if (opts.positional.length) throw new Error('hfs emit-contracts takes no path');
+      const declaration = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8'));
+      const { written, skipped, standIns } = emitContracts({ repoRoot, declaration });
+      for (const file of written) stdout(`wrote ${file}
+`);
+      stdout(`hfs emit-contracts: ${written.length} written${skipped.length ? `, ${skipped.join(', ')} serve no GraphQL` : ''}
+`);
+      for (const [app, lines] of Object.entries(standIns)) {
+        stdout(`${app}: ${lines.length} dependenc${lines.length === 1 ? 'y' : 'ies'} of the resolvers could not load here and stood in (no GraphQL type is affected):\n`);
+        for (const line of lines) stdout(`  ${line}\n`);
+      }
+      return 0;
+    }
+    if (verb === 'new') {
+      const [kind, ...args] = opts.positional;
+      let written;
+      if (kind === 'service' && args.length === 2) written = newService({ repoRoot, dir: args[0], name: args[1], inject: opts.inject ?? [] });
+      else if (kind === 'spec' && args.length === 1 && opts.inject === undefined) written = newSpec({ repoRoot, file: args[0] });
+      else throw new Error('hfs new takes `service <dir> <name> [--inject ...]` or `spec <file>.service.ts`');
+      for (const file of written) stdout(`created ${file}
+`);
+      return 0;
+    }
     if (verb === 'init') {
       if (opts.positional.length) throw new Error('hfs init takes no path');
       const result = initRepo({ repoRoot, write: !opts.stdout });
@@ -92,7 +196,7 @@ export async function main(argv, { stdout = (s) => process.stdout.write(s), stde
     if (opts.json) stdout(`${JSON.stringify(explained, null, 2)}\n`); else printExplain(explained, stdout);
     return explained.status === 'no-slot' || explained.status === 'ambiguous' ? 1 : 0;
   } catch (error) {
-    stderr(error instanceof HfsSlotsError ? `${error.message}\n` : `hfs: ${error.message}\n${USAGE}`);
+    stderr(error instanceof HfsSlotsError || error instanceof SyncError ? `${error.message}\n` : error instanceof ScaffoldError ? `${error.code}: ${error.message}\n` : `hfs: ${error.message}\n${USAGE}`);
     return 2;
   }
 }

package/emit/compiler.mjs

@@ -0,0 +1,35 @@
+/**
+ * The compiler options both emit workers use: the repository's own tsconfig.json, made emit-safe, with the two decorator switches
+ * Nest needs. A configuration that cannot be read completely (an `extends` package that is not installed here) falls back to what
+ * a Nest project compiles with, and each problem is handed to `note` so the caller can report it like a stand-in.
+ */
+import path from 'node:path';
+
+/** Answers the compiler options of the repository at `repoRoot`. */
+export function compilerOptionsOf(ts, repoRoot, note = () => {}) {
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    path.join(repoRoot, 'tsconfig.json'),
+    {},
+    { ...ts.sys, onUnRecoverableConfigFileDiagnostic: (diagnostic) => { throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')); } },
+  );
+  for (const error of parsed.errors) note(`tsconfig.json (${ts.flattenDiagnosticMessageText(error.messageText, ' ')}): compiler options fall back to the Nest defaults`);
+  return {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.CommonJS,
+    esModuleInterop: true,
+    ...parsed.options,
+    experimentalDecorators: true,
+    emitDecoratorMetadata: true,
+    declaration: false,
+    declarationMap: false,
+    sourceMap: false,
+    inlineSourceMap: false,
+    incremental: false,
+    composite: false,
+    tsBuildInfoFile: undefined,
+    noEmit: false,
+    noEmitOnError: false,
+    outDir: undefined,
+    rootDir: undefined,
+  };
+}

package/emit/contracts.mjs

@@ -0,0 +1,97 @@
+/**
+ * `hfs emit-contracts`: writes `contracts/<app>/schema.graphql` for every api app of hfs.json that serves GraphQL, and
+ * `contracts/<app>/openapi.json` for every api app whose `apps/<app>/src/operations.ts` exports the typed operation table
+ * `OPERATIONS` (operations.mjs: OpenAPI 3.1 read from the TypeScript checker; nothing is executed).
+ *
+ * The snapshot is `printSchema(lexicographicSortSchema(schema))`, nothing else, so it is deterministic and never carries a
+ * generator banner. It needs no environment, no database and no network, and never boots the app.
+ *
+ * What an app serves is decided from its source (`static-graph.mjs`): the module graph is walked from `AppModule` of
+ * `apps/<app>/src/app.module.ts` through every import (imports of imports, `register`/`forRoot`/`forRootAsync` dynamic modules,
+ * `forwardRef`, spreads and both branches of a conditional), and the resolver providers of the modules the GraphQL server reads
+ * (all of them, or the `include` whitelist and its imports) are the resolvers of the contract. The schema itself comes from
+ * Nest's own `GraphQLSchemaFactory` (the builder the running server uses) over those classes, compiled the way `tsc` compiles
+ * them. An app whose graph holds no GraphQL server is skipped; an app whose graph cannot be decided is an error.
+ *
+ * TypeScript, Nest and graphql are the repository's own packages; nothing is added to the managed devDependencies. Every app
+ * runs in its own child process (`schema-worker.mjs`) because Nest GraphQL's type metadata is process-global.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openapiPath } from './operations.mjs';
+
+/** The stderr prefix of a dependency the worker could not load and stood in for. */
+export const STAND_IN = 'stand-in ';
+const WORKER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'schema-worker.mjs');
+const OPERATIONS_WORKER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'operations-worker.mjs');
+
+/** The repository-relative path of an app's root module. */
+export const appModulePath = (app) => `apps/${app}/src/app.module.ts`;
+
+/** The repository-relative path of an app's snapshot. */
+export const snapshotPath = (app) => `contracts/${app}/schema.graphql`;
+
+/** The `paths` aliases of a tsconfig as [{ prefix, targets }], `@modules/*` giving prefix `@modules/`. Pure. */
+export function aliasesOf(paths, baseDir) {
+  return Object.entries(paths ?? {})
+    .filter(([pattern]) => pattern.endsWith('/*'))
+    .map(([pattern, targets]) => ({ prefix: pattern.slice(0, -1), targets: targets.map((target) => path.resolve(baseDir, target.replace(/\*$/, ''))) }));
+}
+
+/** The absolute base a specifier resolves to through the aliases, or null when it is not aliased. Pure. */
+export function aliasTarget(aliases, specifier) {
+  const alias = aliases.find((item) => specifier.startsWith(item.prefix));
+  return alias ? path.join(alias.targets[0], specifier.slice(alias.prefix.length)) : null;
+}
+
+/** The api apps of a declaration that can serve GraphQL: kind `api`. Pure. */
+export const apiApps = (declaration) => (declaration.apps ?? []).filter((app) => app.kind === 'api').map((app) => app.name);
+
+/** The text written to a snapshot file: the printed schema and one final newline. Pure. */
+export const snapshotText = (printed) => `${printed.replace(/\n+$/, '')}\n`;
+
+/** Runs one worker of one app; answers its stdout, or null when the app has nothing of that kind (exit 3). */
+function runWorker(worker, repoRoot, app) {
+  const result = spawnSync(process.execPath, [worker, repoRoot, app], { encoding: 'utf8', cwd: repoRoot, env: { PATH: process.env.PATH ?? '' }, maxBuffer: 256 * 1024 * 1024 });
+  if (result.status === 3) return { text: null, lines: [] };
+  const lines = (result.stderr ?? '').split(/\r?\n/).filter(Boolean);
+  if (result.status !== 0) throw new Error(`hfs emit-contracts: ${app} failed (exit ${result.status}): ${(lines.join('\n') || result.stdout).trim()}`);
+  return { text: result.stdout, lines: lines.filter((line) => line.startsWith(STAND_IN)) };
+}
+
+/** Emits the GraphQL schema and the operations of one app: `{ graphql, openapi, standIns }`, each text or null. */
+function emitApp(repoRoot, app) {
+  const graphql = runWorker(WORKER, repoRoot, app);
+  const operations = runWorker(OPERATIONS_WORKER, repoRoot, app);
+  return { graphql: graphql.text, openapi: operations.text, standIns: [...graphql.lines, ...operations.lines] };
+}
+
+/**
+ * Writes the snapshots of every api app: `contracts/<app>/schema.graphql` when it serves GraphQL and `contracts/<app>/openapi.json`
+ * when it has an operation table. Answers `{ written: [paths], skipped: [apps], standIns: { app: [lines] } }`, `skipped` being the
+ * apps with neither. `declaration` is the parsed hfs.json. `outDir` (absolute) redirects the snapshots to another root, keeping
+ * their relative paths.
+ */
+export function emitContracts({ repoRoot, declaration, outDir = repoRoot }) {
+  const written = [];
+  const skipped = [];
+  const standIns = {};
+  for (const app of apiApps(declaration)) {
+    const emitted = emitApp(repoRoot, app);
+    if (emitted.graphql === null && emitted.openapi === null) {
+      skipped.push(app);
+      continue;
+    }
+    for (const [text, relative] of [[emitted.graphql, snapshotPath(app)], [emitted.openapi, openapiPath(app)]]) {
+      if (text === null) continue;
+      const target = path.join(outDir, relative);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, snapshotText(text));
+      written.push(relative);
+    }
+    if (emitted.standIns.length) standIns[app] = emitted.standIns;
+  }
+  return { written, skipped, standIns };
+}

package/emit/operations-worker.mjs

@@ -0,0 +1,24 @@
+// The child process of `hfs emit-contracts` for the OPERATIONS of ONE app: `node operations-worker.mjs <repoRoot> <app>`.
+// Prints the OpenAPI 3.1 document of the app's typed operation table on stdout; exit 3 when the app has no `apps/<app>/src/operations.ts`.
+// Loads the repository's own typescript (resolved from the repository, never from hfs). Nothing of the repository is executed.
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { compilerOptionsOf } from './compiler.mjs';
+import { openApiText, operationsPath, readOperations } from './operations.mjs';
+
+const [rootArgument, app] = process.argv.slice(2);
+const repoRoot = path.resolve(rootArgument);
+const file = path.join(repoRoot, operationsPath(app));
+if (!fs.existsSync(file)) process.exit(3);
+const ts = createRequire(path.join(repoRoot, 'package.json'))('typescript');
+const options = compilerOptionsOf(ts, repoRoot, (message) => process.stderr.write(`stand-in ${message}\n`));
+const program = ts.createProgram({ rootNames: [file], options });
+try {
+  const { operations, components } = readOperations({ ts, program, file });
+  process.stdout.write(openApiText({ app, operations, components }));
+} catch (error) {
+  process.stderr.write(`${error.message}
+`);
+  process.exit(1);
+}