@starci/hfs 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.0 - 2026-10-01
+
+- Breaking: one entry, `hfs lint`. It runs the repository's eslint, the `hfs check` repository pass and, for a front end, stylelint, and writes one `starci/lint@1` report; `--sonar <file>` writes the single Sonar import (engines starci-hfs, eslint and stylelint in one document); `--changed <files...> --format json` is the land-gate shape. `hfs report`, `hfs check --sonar` and the managed scripts `lint:check`, `lint:report`, `hfs:check` and `hfs:report` are deleted; the managed `lint` script is `hfs lint`, and CI, hooks and the Sonar template read `reports/lint.sonar.json`.
+- Changed: 48 TS-attached architecture checks are served to eslint through one cached project graph (the `project-graph` law of both canons); `hfs check` keeps only findings with no TS file to sit on. The machine `size-growth` is gone (eslint `file-size-growth` holds the law).
+- Fixed: workspace package imports resolve to their source (package `exports`/`types` mapped from dist to src through the package tsconfig), so `hfs check` needs no build and consumed exports are not reported unused; `ARCH_OWNER_EXPORT_BYPASS` accepts every entry the package's `exports` maps.
+
+- Changed: Back-end apps have no composition spec. App slots admit only their production composition files, and R102 rejects a spec under `apps/<app>/src`. The e2e world proves that each app boots.
+
+## 2.0.2 - 2026-10-01
+
+- Fixed: `hfs` printed nothing and checked nothing when started through a node_modules junction or symlink (every lane worktree, some npx shims): the entry-point test compared `argv[1]` with the resolved module path. It now compares real paths (`isMain` of `scripts/checks/common.mjs`, shared by the bin and the architecture entry). Spec: `tests/hfs-cli-worktree.spec.mjs` runs `hfs check` inside a `git worktree add` checkout with a junctioned node_modules and requires a report or a loud refusal.
+
 ## 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.

package/README.md

@@ -6,8 +6,8 @@ catalog slice, the loader and the architecture machine with every file it import
 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] [--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 lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]   # THE lint entry (`npm run lint`): exit 0 clean, 1 findings, 2 a tool could not run
+npx hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]   # the repository pass alone (what `hfs lint` runs for the findings that have no TypeScript file); exit 1 on any error-level finding
 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]
@@ -53,7 +53,7 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `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_CI_MISSING_CANON` | error | `ci.yml` without a `run:` step of `hfs lint` (`npm run lint`, or `npx hfs lint` at the pinned version), or `.husky/pre-push` without `npm run typecheck` and `npm run lint` (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`) |
@@ -75,11 +75,11 @@ The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the
 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
+and the `scripts` block (`lint` is the one lint gate, `hfs lint`: ESLint over the repository, the repository check and, for a front end, stylelint; `lint:fix` is the same with `--fix`; 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,
+direction, owner public API, cycles, module registration and composition, clones, dead exports, required files,
 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.
@@ -88,7 +88,7 @@ repository without `typescript` installed fails with `ARCH_TYPESCRIPT_MISSING`;
 `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.
+pass.
 
 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.
@@ -98,22 +98,18 @@ except `hfs init`, which writes `hfs.json` only when none exists.
 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 |
+One entry, one report, one file: `npm run lint` is `hfs lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `hfs check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and, for a front end, `stylelint` (rule id = the stylelint rule). `hfs lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
 
-`--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;
+`--sonar` writes the findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
+failing lint 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
+The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths` (`reports/lint.sonar.json` only) and no `sonar.host.url` (the host is
+`SONAR_HOST_URL`); the managed CI workflow produces the report and runs the scan and the gate action with `!cancelled()`, so a failed lint step still
+reaches Sonar while the job stays failed. There is no `continue-on-error`. Both profiles run `npm run lint -- --sonar reports/lint.sonar.json` once, before the scan. 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,

package/bin/hfs.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // hfs - the HFS command line of a StarCi product repository.
-//   hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>] [--sonar <file>]
+//   hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]
 //                                            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
@@ -11,15 +11,14 @@
 //                                            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
+//                                            overrides it); 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 lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]
+//                                            the ONE lint entry (npm run lint): ESLint (canon per-file rules and the project-graph rules)
+//                                            plus this check's repository findings plus stylelint, as one starci/lint@1 report; --sonar writes
+//                                            the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
 //   hfs explain <path> [--repo <dir>] [--json]   which slot owns the path, its tier, allowed imports, required tests.
 //   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.
@@ -35,6 +34,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isMain } from '../runtime/scripts/checks/common.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';
@@ -44,10 +44,11 @@ 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';
+import { lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
+import { writeReport } from '../report/sonar.mjs';
 
-const USAGE = `hfs check [--repo <dir>] [--json] [--fast] [--base <ref>] [--sonar <file>]
-hfs report <eslint|stylelint> <in> <out> [--repo <dir>]
+const USAGE = `hfs check [--repo <dir>] [--json] [--fast] [--base <ref>]
+hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]
 hfs init [--repo <dir>] [--stdout]
 hfs emit-contracts [--repo <dir>]
 hfs explain <path> [--repo <dir>] [--json]
@@ -57,7 +58,7 @@ hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<mo
 hfs new spec <file>.service.ts [--repo <dir>]
 `;
 const PER_CODE_LIMIT = 25;
-const VALUE_FLAGS = new Set(['--repo', '--base', '--sonar', '--inject']);
+const VALUE_FLAGS = new Set(['--repo', '--base', '--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']);
@@ -96,13 +97,6 @@ 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') {
@@ -120,47 +114,58 @@ function printExplain(e, out) {
   if (e.code) out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
 }
 
+/** The repository pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface. `only` limits the formatter to those files. */
+async function runCheck({ repoRoot, fast = false, base, only, presets, prettier }) {
+  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 }), ...(fast ? [] : await formatFindings({ repoRoot, files: only ?? 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 (fast) 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, base, extraFindings });
+  if (contracts) result.contracts = contracts;
+  return result;
+}
+
+/** `hfs lint`: ESLint, the repository checks and (front end) stylelint as one report; see lint/run.mjs. */
+async function lintMain(argv, { stdout, presets, prettier }) {
+  const opts = parseLintArgs(argv);
+  const repoRoot = path.resolve(opts.repo ?? process.cwd());
+  const { report, sonar, exit } = await lintRepository({
+    repoRoot, opts, trackedFiles,
+    hfsCheck: (root) => runCheck({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
+  });
+  if (opts.sonar !== undefined) writeReport(path.resolve(opts.sonar), sonar);
+  if (opts.format === 'json') stdout(`${JSON.stringify(report, null, 2)}
+`); else printLintText(report, stdout);
+  return exit;
+}
+
 /** `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', 'report', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
+  if (!['check', 'lint', 'init', 'explain', 'sync', 'work-hygiene', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
   try {
     if (verb === 'sync' || verb === 'work-hygiene') return await syncMain(argv);
+    if (verb === 'lint') return await lintMain(rest, { stdout, presets, prettier });
     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 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.base !== undefined && opts.fast !== true) throw new Error('--base names the ref --fast compares with; it needs --fast');
+      const result = await runCheck({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier });
       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'));
@@ -201,4 +206,6 @@ export async function main(argv, { stdout = (s) => process.stdout.write(s), stde
   }
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = await main(process.argv.slice(2));
+// Run when this file is the entry point, compared by real path: through a node_modules junction or an npx shim argv[1] is
+// the junction path while import.meta.url is the resolved one, and a plain comparison silently skipped main (hfs printed nothing).
+if (isMain(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/lint/run.mjs

@@ -0,0 +1,130 @@
+// hfs lint - the ONE lint entry and the ONE report of a StarCi repository.
+//
+//   hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]
+//
+// It runs, over the repository (or over the files named by --changed):
+//   1. ESLint through the repository's own install and eslint.config.mjs (the canon plugin: the per-file rules and the project-graph
+//      rules of the architecture machine, findings on the line of the offending TypeScript file);
+//   2. `hfs check` for what has no TypeScript file to sit on (the tree, managed files, pins, CI, contracts, docs, .starciwork);
+//   3. stylelint when --stylelint names the style glob (front ends).
+// Their findings become one list of one shape (`starci/lint@1`). `--format json` prints that report on stdout; `--sonar <file>` writes the
+// same findings as THE Sonar Generic Issue Import file (engine ids starci-hfs, eslint, stylelint in one document); the exit code is the
+// land-gate input: 0 no finding, 1 at least one, 2 a tool could not run (never a pass).
+// --changed restricts ESLint and stylelint to the listed files and keeps of the repository findings only those on a listed file or on no file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { linterReport, mergeReports, sonarReport, sourceRootsOf } from '../report/sonar.mjs';
+
+export const LINT_SCHEMA = 'starci/lint@1';
+const CODE_PREFIX = /^\[([A-Z][A-Z0-9_]+)\] /;
+const posix = (file) => String(file).replace(/\\/g, '/').replace(/^\.\//, '');
+
+/** The flags of `hfs lint`; `--changed` takes every argument up to the next flag. */
+export function parseLintArgs(argv) {
+  const opts = { changed: null, fix: false, format: 'text', repo: undefined, sonar: undefined, stylelint: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--changed') {
+      opts.changed = [];
+      while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) opts.changed.push(posix(argv[++i]));
+    } else if (arg === '--fix') opts.fix = true;
+    else if (['--format', '--repo', '--sonar', '--stylelint'].includes(arg)) {
+      if (argv[i + 1] === undefined) throw new Error(`${arg} needs a value`);
+      opts[arg.slice(2)] = argv[++i];
+    } else throw new Error(`unknown argument ${arg}`);
+  }
+  if (!['text', 'json'].includes(opts.format)) throw new Error('--format is text or json');
+  return opts;
+}
+
+/** A linter's json results through the repository's own install: `{ results }` or `{ error }`. */
+function runLinter({ repoRoot, pkg, bin, args }) {
+  let entry;
+  try {
+    const manifest = createRequire(path.join(repoRoot, 'package.json')).resolve(`${pkg}/package.json`);
+    const declared = JSON.parse(fs.readFileSync(manifest, 'utf8')).bin;
+    entry = path.join(path.dirname(manifest), typeof declared === 'string' ? declared : declared[bin]);
+  } catch {
+    return { error: `${pkg} is not installed under ${repoRoot}` };
+  }
+  const run = spawnSync(process.execPath, [entry, ...args], { cwd: repoRoot, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 });
+  // The linters exit 1 when they found something; no json at all means they could not run.
+  let results;
+  try { results = JSON.parse(run.stdout); } catch { return { error: `${pkg} produced no json report (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n')[0]}` }; }
+  if (!Array.isArray(results)) return { error: `${pkg} produced a report that is not a result list` };
+  return { results };
+}
+
+const eslintFindings = (results, repoRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
+  engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: 'error',
+  path: posix(path.relative(repoRoot, result.filePath)), line: message.line ?? null, column: message.column ?? null, message: message.message,
+})));
+
+const stylelintFindings = (results, repoRoot) => results.flatMap((result) => (result.warnings ?? []).map((warning) => ({
+  engine: 'stylelint', rule: warning.rule || 'stylelint-error', code: null, severity: 'error',
+  path: posix(path.relative(repoRoot, result.source)), line: warning.line ?? null, column: warning.column ?? null, message: warning.text,
+})));
+
+const byLocation = (a, b) => `${a.path ?? ''}:${String(a.line ?? 0).padStart(7, '0')}:${a.rule}`.localeCompare(`${b.path ?? ''}:${String(b.line ?? 0).padStart(7, '0')}:${b.rule}`);
+
+/**
+ * Run the whole lint of a repository. `hfsCheck(repoRoot)` returns the `hfs check` result (`{ findings, tracked }`); the CLI injects it.
+ * Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
+ */
+export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [] }) {
+  const changed = opts.changed === null ? null : new Set(opts.changed);
+  const existing = changed ? [...changed].filter((file) => fs.existsSync(path.join(repoRoot, file))) : [];
+  const errors = [];
+  const findings = [];
+  const raw = { eslint: [], stylelint: [] };
+  const engines = {};
+
+  const sources = existing.filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
+  if (changed === null || sources.length) {
+    const linted = runLinter({ repoRoot, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : ['.'])] });
+    if (linted.error) errors.push(linted.error);
+    else { raw.eslint = linted.results; findings.push(...eslintFindings(linted.results, repoRoot)); }
+    engines.eslint = { files: changed ? sources.length : null };
+  } else engines.eslint = { files: 0, skipped: 'no changed source file' };
+
+  if (opts.stylelint !== undefined) {
+    const styles = existing.filter((file) => file.endsWith('.css'));
+    if (changed === null || styles.length) {
+      const linted = runLinter({ repoRoot, pkg: 'stylelint', bin: 'stylelint', args: [...(changed ? styles : [opts.stylelint]), '--formatter', 'json', ...(opts.fix ? ['--fix'] : [])] });
+      if (linted.error) errors.push(linted.error);
+      else { raw.stylelint = linted.results; findings.push(...stylelintFindings(linted.results, repoRoot)); }
+    }
+    engines.stylelint = { files: changed ? styles.length : null };
+  }
+
+  let checked = { findings: [] };
+  try { checked = await hfsCheck(repoRoot); } catch (error) { errors.push(`hfs check could not run: ${String(error?.message ?? error)}`); }
+  const repoErrors = checked.findings.filter((finding) => finding.level === 'error');
+  const kept = changed === null ? repoErrors : repoErrors.filter((finding) => !finding.path || changed.has(posix(finding.path)));
+  for (const finding of kept) {
+    findings.push({ engine: 'hfs', rule: finding.code, code: finding.code, severity: 'error', path: finding.path ? posix(finding.path) : null, line: finding.line ?? null, column: finding.column ?? null, message: finding.message, titleVi: finding.titleVi, nextStepVi: finding.nextStepVi });
+  }
+  engines.hfs = { findings: kept.length };
+  findings.sort(byLocation);
+
+  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 tracked = sourceRoots.length ? trackedFiles(repoRoot) : [];
+  const sonar = mergeReports([
+    sonarReport(kept, { sourceRoots, tracked }),
+    linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
+    ...(opts.stylelint !== undefined ? [linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked })] : []),
+  ]);
+  const report = { schema: LINT_SCHEMA, ok: findings.length === 0 && errors.length === 0, repoRoot, changed: changed ? [...changed].sort() : null, counts: { error: findings.length }, engines, errors, findings };
+  return { report, sonar, exit: errors.length ? 2 : findings.length ? 1 : 0 };
+}
+
+export function printLintText(report, out) {
+  for (const f of report.findings) out(`${f.path ?? '-'}${f.line ? `:${f.line}${f.column ? `:${f.column}` : ''}` : ''}  ${f.engine}/${f.rule}  ${f.message}\n`);
+  for (const e of report.errors) out(`ERROR ${e}\n`);
+  const per = Object.keys(report.engines).map((engine) => `${engine} ${report.findings.filter((f) => f.engine === engine).length}`).join(', ');
+  out(`\nhfs lint: ${report.counts.error} finding${report.counts.error === 1 ? '' : 's'} (${per})${report.errors.length ? `, ${report.errors.length} tool error${report.errors.length === 1 ? '' : 's'}` : ''}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "The HFS command line of a StarCi product repository: hfs check, init, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",
@@ -15,6 +15,7 @@
   "files": [
     "bin/hfs.mjs",
     "emit/**",
+    "lint/**",
     "scaffold/**",
     "report/**",
     "runtime/**",

package/report/sonar.mjs

@@ -1,13 +1,10 @@
-// hfs report: the ONE way the findings of the StarCi canon reach Sonar (contract change hfs-sonar-import).
-//
-//   hfs check --sonar <file>               writes every error-level finding of the check (repository, managed files and the whole
-//                                          architecture machine) as a Sonar Generic Issue Import document (SonarQube 10.3+ format:
-//                                          `{ rules, issues }`), engineId `starci-hfs`, rule id = the finding code
-//   hfs report <eslint|stylelint> <in> <out>
-//                                          converts the linter's own json output (`eslint -f json`, `stylelint --formatter json`)
-//                                          into the same document format, engineId `eslint` / `stylelint`, rule id = the linter's
-//                                          rule. Sonar's own ESLint import (sonar.eslint.reportPaths) is not used: it drops an issue
-//                                          on a file outside sonar.sources, and a stylelint result has no native import at all.
+// Sonar documents of the ONE lint entry `hfs lint` (contract changes hfs-sonar-import, hfs-lint-entry): the building blocks that turn the
+// findings of the StarCi canon into a Sonar Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`).
+//   sonarReport(findings)        the repository findings of `hfs check`, engineId `starci-hfs`, rule id = the finding code
+//   linterReport(kind, results)  a linter's own json output (`eslint -f json`, `stylelint --formatter json`), engineId `eslint` / `stylelint`,
+//                                rule id = the linter's rule. Sonar's own ESLint import (sonar.eslint.reportPaths) is not used: it drops an
+//                                issue on a file outside sonar.sources, and a stylelint result has no native import at all.
+//   mergeReports(reports)        the documents of one `hfs lint` run as ONE file (reports/lint.sonar.json, sonar.externalIssuesReportPaths)
 // One placement rule for every engine: Sonar imports an issue only on a file it indexes (a tracked source or stylesheet under
 // sonar.sources). A finding on any other path (hfs.json, a workflow, a package under an unindexed root, e2e/, a directory) is filed
 // on the first source file of sonar.sources and its message names the real path, so no finding is dropped.
@@ -42,6 +39,12 @@ function document(rules, issues) {
   return { rules: [...rules.values()].filter((rule) => used.has(rule.id)).sort((a, b) => cmp(a.id, b.id)), issues: sorted };
 }
 
+/** One document of several (the starci-hfs, eslint and stylelint documents of one `hfs lint` run): rules by id, issues in the one sort order. */
+export function mergeReports(reports) {
+  const rules = new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule]));
+  return document(rules, reports.flatMap((report) => report.issues));
+}
+
 /**
  * The first source file of the repository (sorted) under one of `sourceRoots`: Sonar imports an issue only on a file it
  * indexes, and a finding about hfs.json, a workflow, a config file or a directory is not on one, so it is filed on this
@@ -106,7 +109,6 @@ const LINTERS = Object.freeze({
     text: (message) => message.message,
     describe: (id) => `ESLint rule ${id} of the StarCi canon (@starci/eslint-canon-be and @starci/eslint-canon-fe) or of a plugin it composes.`,
     describeError: 'ESLint could not lint a file: a parse error or an invalid configuration.',
-    shape: 'an array of results with a filePath and messages',
   },
   stylelint: {
     engine: STYLELINT_ENGINE,
@@ -117,11 +119,10 @@ const LINTERS = Object.freeze({
     text: stylelintText,
     describe: (id) => `Stylelint rule ${id} of the StarCi CSS canon (@starci/stylelint-canon, HFS R61).`,
     describeError: 'Stylelint could not read a stylesheet: a parse error or an invalid option.',
-    shape: 'an array of results with a source and warnings',
   },
 });
 
-export const LINTER_KINDS = Object.freeze(Object.keys(LINTERS));
+const LINTER_KINDS = Object.freeze(Object.keys(LINTERS));
 
 /**
  * A linter's json results (`eslint -f json`: [{ filePath, messages: [{ ruleId, line, endLine, message }] }]; `stylelint
@@ -162,19 +163,3 @@ export function writeReport(file, report) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, `${JSON.stringify(report, null, 2)}\n`);
 }
-
-/** `hfs report <eslint|stylelint> <in> <out> [--repo <dir>]`: convert a linter's json report; returns the number of issues written. */
-export function convertReportFile({ kind, input, output, root, sourceRoots = [], tracked = [] }) {
-  const linter = LINTERS[kind];
-  if (linter === undefined) throw new Error(`unknown linter ${kind}; expected ${LINTER_KINDS.join(' or ')}`);
-  let results;
-  try {
-    results = JSON.parse(fs.readFileSync(input, 'utf8'));
-  } catch (error) {
-    throw new Error(`${input} is not a readable ${kind} json report (${error.message})`);
-  }
-  if (!Array.isArray(results)) throw new Error(`${input} is not a ${kind} json report: expected ${linter.shape}`);
-  const report = linterReport(kind, results, { root, sourceRoots, tracked });
-  writeReport(output, report);
-  return report.issues.length;
-}

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -10,33 +10,33 @@ pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
   '@starci/grammar':
-    version: 0.7.2
+    version: 0.8.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
-    why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.7.2 (Input tel kind and IconButton disclosure props).
+    why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.8.0 (the brand layer sets `--font-sans` and `--font-mono`; the grammar reads them; 0.7.2 added the Input tel kind and IconButton disclosure props).
   '@starci/eslint-canon-be':
-    version: 2.0.1
+    version: 2.1.0
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: '2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws (R36 sql-text-only, R83 no-repository-class, R85/R87/R89 service-deps, R43 config-parsed-in-main, R47/R48 test world, R95 operations, R98-R101 builders).'
   '@starci/eslint-canon-fe':
-    version: 7.0.0
+    version: 7.1.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: '7.0.0: the front end has no tests (test rules removed, FE_NO_TESTS R97 in hfs); no-vietnamese-in-source (R91).'
   '@starci/stylelint-canon':
-    version: 2.0.0
+    version: 2.0.1
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
-    why: '2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
+    why: '2.0.1 accepts `--font-sans` and `--font-mono` in the brand layer (the vocabulary follows the grammar 0.8.0). 2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
   '@starci/tsconfig':
     version: 2.0.0
     group: starci
@@ -57,7 +57,7 @@ pins:
     source: packages/jest-preset/package.json
     why: '2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/hfs':
-    version: 2.0.1
+    version: 3.0.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/sonar-gate.yaml

@@ -32,13 +32,14 @@ newCode:
     metric: new_security_hotspots_reviewed
     minReviewedPercent: 100
     unreviewedMax: 0
-# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE pipeline
-# (packages/hfs, contract change hfs-sonar-import) and the gate holds the open-issue count of the whole project at zero:
-#   starci-hfs   `hfs check --sonar reports/hfs.sonar.json` (repository, managed-file and architecture-machine findings;
-#                the rule id is the finding code) -> sonar.externalIssuesReportPaths
-#   eslint       `eslint -f json -o reports/eslint.json` (the BE and FE canon plugins alike) converted by `hfs report eslint` -> sonar.externalIssuesReportPaths
-#   stylelint    `stylelint --formatter json` converted by `hfs report stylelint` -> sonar.externalIssuesReportPaths
-# The three imports share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own
+# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `hfs lint`
+# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry), which writes ONE file, reports/lint.sonar.json
+# (`npm run lint -- --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
+# the whole project at zero. The file carries three engines:
+#   starci-hfs   the repository findings of `hfs check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
+#   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)
+#   stylelint    stylelint's json over the style glob (front ends)
+# The engines share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own
 # ESLint import (sonar.eslint.reportPaths) is not used because it drops such issues.
 # A SonarQube gate condition cannot filter issues by engine, so the condition is the project's open issues (`violations`,
 # overall code): the three engines above are the imports it counts, and every native Sonar issue counts with them. That is