Audit: inline /** @type {T} */ (v) casts - #1586

Works out the `fjs` route from eslint.md: the three rules that matter are
syntactic, so a token-stream scan is enough, and the tokenizer already keeps a
JSDoc block's leading `*` so `/** … */` is distinguishable without parsing.

A prototype of the inline-cast rule over all 260 `.mjs` files reproduces 221 of
221 `@type {const}` sites and 353 of 357 inline casts found by the audit — but
also 24,166 error tokens across 251 files. The tokenizer accepts neither
single-quoted strings nor template literals, the two forms the repository is
written in. That also explains the misses: `'/*'` inside a single-quoted string
opens a phantom block comment that swallows the following cast, which is why
three of the four missed sites are in the tokenizer's own module.

Completing the tokenizer is therefore step one, and worth doing on its own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih

Matching `@type\s*\{` against comment text is a hack. A JSDoc block is a
language — a tag sequence, brace-delimited type expressions in a TypeScript
subset, inline `{@link}`, free text — and it belongs in the transducer stack
`fjs/bnf/todo/layered-parser.md` already describes, as one more layer above the
JS tokenizer. Even the inline-cast rule needs it: exempting `@type {const}`
means knowing the type body *is* the identifier `const`, not that it contains
the word.

Sizes the subset from what the tree actually writes: 3772 type bodies, led by
function types (1318), generics (1128), `readonly` (492) and array types (257),
with a small but real tail of conditional types, `infer`, `import('…')` and
intersections that a stunted subset would miss.

The unknown-tag rule already has two live targets, both silently ignored by
TypeScript: `@result` on `fromArrayLike` where `@returns` was meant, so its
declared return type does not exist; and `@remark` for `@remarks`.

Renames fjs-lint.md to jsdoc-parser.md, since the parser is the substance and
the lint rules are the smallest useful thing to build on it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih

…grammar

The previous revision proposed a grammar for a subset of TypeScript's type
expressions. That is the superset FunctionalScript exists to avoid, rebuilt in
the repository's own BNF. Under `/*: expr */` there is no type grammar at all:
a type is a value from `fjs/types/rtti`, an annotation is an ordinary
expression, and the existing parser already reads it. The tokenizer keeps a
block comment's body verbatim, so `': myType '`, `'* @type {X} '` and
`' plain '` differ in their first character — which is what lets the two
annotation forms coexist while the tree migrates.

Records what is already built: `validate`/`parse`, the canonical `data` form
with `subset` (assignability as a decidable operation), and `rtti/ts`, which is
already a printer from schemas to canonical TypeScript aliases — the `.d.ts`
generator half.

And the open questions: compile-time staging of annotation expressions;
inferring an RTTI for a non-literal right-hand side so `subset` has two
operands; and function types, which `Type` has no case for even though 1318 of
the tree's 3772 JSDoc type bodies are function types.

Renames jsdoc-parser.md accordingly and marks the lint rules transitional.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih

`/*: type */` + RTTI is a direction, not a plan: it needs the compiler's own
parser to see the annotation and the compiler to evaluate a module at compile
time (`fjs/fsc/todo/47.md`). Dropped to P5 and marked gated, with its near-term
proposal steps rewritten as a sketch and the dependencies made explicit. Until
it arrives, TypeScript and the standard toolchain are the checker.

Adds `todo/strict-static-analysis.md` as the umbrella. The asymmetry it names:
CI holds Rust to `clippy -- -D warnings` and `fmt --check` across nine targets,
while the JavaScript half runs `tsc` and the test suites and nothing else — no
lint, no formatting check, no unused-code check, no package-correctness check.
Surveys what each candidate catches that the others do not, and notes that
`deno.json` already configures `fmt` and both Deno and Bun are already on the
runners, so two of the checks cost no setup at all. Also records that CI is
generated from `fjs/ci/`, so a new check is a change there, not to the YAML.

Reframes eslint.md accordingly: ESLint is the near-term answer because it is
the only route to type-aware rules, and `fjs lint` waits with the compiler.

Adds the tokenizer gap as its own module-scoped issue: it accepts neither
single-quoted strings nor template literals, the two forms this repository is
written in.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih

`spec/todo/2460-js-string-literals.md` already covers single-quoted strings,
and covers them better: JSON string syntax across JSON ⊂ DJS ⊂ FS is a design
decision with a stated rationale, not an omission, and the documented
workaround is to normalize `'x'` to `"x"` rather than to extend the grammar.
The new issue also had the framing backwards — the tokenizer rejecting this
repository's `.mjs` sources is those sources not yet being FunctionalScript,
which migrate-typescript-to-mjs.md stage 3 covers, not a tokenizer defect.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih

`2460-js-string-literals` excludes them explicitly — a substitution embeds an
expression, so this is FJS-level sugar (§3.4) rather than lexical sugar at the
DJS level — but nothing tracked them afterwards.

Records the semantics as concatenation, and three questions to settle before
implementing: whether substitutions follow ECMAScript's implicit `ToString`
(which is the coercion FunctionalScript avoids elsewhere) or must already be
strings; whether tagged templates are in scope at all; and how a
substitution-free template stays distinguishable from the JSON string it
denotes, which content addressing needs.

Notes the migration cost for the same reason 2460 does: 202 of the 260 `.mjs`
files use template literals, with 494 substitutions between them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih

It is a language feature the `fjs` parser does not recognize yet, which is what
spec/todo is for — so it drops the todo/ issue header for spec-draft style,
sits next to 3370-type-inference in §3.3, and is registered in the spec README.
Placing it there also puts the contrast with the TC39 Type Annotations proposal
(§4.1) in view: that one is erasable syntax with no checker, this one is a
comment plus a checker that is an ordinary library.

Two of its open questions turned out to have homes already. Function types are
`fjs/types/rtti/todo/668-rtti-function-types.md`, which independently reached
the same conclusion — a function can be checked as callable, but its contract
is only observable when called — so the question left here is narrower: what an
annotation on a function should mean. Inference is 3370, now cross-linked both
ways. Nominal types genuinely have no issue, and that is now stated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQcZKuWSt2rEZrCj1jVZih