@inlang/core/lint

[samuelstroschein]

Problem

The CLI, Editor, and IDE extension require lints and filters based.

[samuelstroschein]

Proposal

Develop a dedicated @inlang/core/lint module that takes the AST and extends it with an additional node lint that provides additional information such as "missing translation etc".

const resources = config.readResources()
const resourcesWithLints = lint(resources)

// @inlang/core/query still works
// with linted resources provides additional information 

const message = query(resourcesWithLints)
if (message.lint.error){
  console.log(message.lint.error.message)
  console.log(message.lint.error.type)
}

Pros

• unobtrusive extension of the AST by adding a node (this approach can scale to other AST extensions)
• lint information exists at the node level without an extra query package

Cons

• the query package must be generic for typesafety
• the query package should likely be extended too e.g. query(resourceWithLints).hasLintErrors() etc.

[samuelstroschein]

The lint module could be return an extended query module and thereby extend query:

const _resources = config.readResources() 
const { resources, query } = lint(_resources)

[ivanhofer]

From the code examples I don't fully understand what query does. Can you please explain your intentions?

[samuelstroschein]

The @inlang/core/query module exists for CRUD operations on the AST.

@inlang/core/query return type would need to be partially generic to include properties of "AST extensions" such as a lint extension e.g.

const resourceWithLints = lint(resource);
const message = query(resourceWithLints).get("first-message");
// how would we get typesafety for the following line?
// the current implementation of `query` returns a `Message` but should likely return `Message<WithLints>`
if (message.lint.error){
  //
}

One way (without generics) would be if an extension like lint returns a superset query function. I prefer the generic approach to decouple both modules though.

Did I explain my cause?

[ivanhofer]

I already thought that this is the use-case. With this example it is more clear. Thanks.
No need to return an extra query from lint. With generics the regular query function is able to return the correct type.

[ivanhofer]

Adding the lint information to the existing nodes in the AST makes sense to me.
The lint function would return a slightly different Resource type. Something like this:

export type Resource = Node<"Resource"> & {
    languageTag: LanguageTag
-    body: Array<Message>
+   body: Array<Message & LintInformation>
}

+export type LintInformation = {
+   errors: LintMessage[]
+   warnings: LintMessage[]
+}

+export type LintMessage = {
+   type: LintType
+   // ... additional type specific properties
+}

+export type LintType = 'missing_key' // ... and others

I'm imagine an additional function is needed to be able to easily iterate over all lint errors without traversing the tree manually.

Things that could be detected by the linter:

• reference language contains key A, but it is missing on one of the translated resources
• (future) parameter is missing; Hallo {name} => Hallo!
• sign missing at the end of a sentence: Hello! => Hallo
• duplicated translations
• a translation is x times longer as original message and could probably look weird in the UI
• anything else?

The inlang config will probably also need a lint configuration option where a user can specify lint-specific settings e.g. disable certain lint rules, use a warning instead of an error etc.

[samuelstroschein]

Sounds good. DX wise the bottom syntax is better, right?

The AST nodes probably need to be generic as well as extensions.

type Resources<Extension> = Node<"Resource"> & Extension & {
    //
}

[ivanhofer]

A question that remains is whether added properties should only be added to metadata

metadata is intended to be used by plugin authors and therefore cannot be typed, right? So adding lint there does not make sense.

The AST nodes probably need to be generic as well as extensions.

Yes, I think so. But let's see what we come up with.

[samuelstroschein]

metadata is intended to be used by plugin authors and therefore cannot be typed, right? So adding lint there does not make sense.

Correct. Metadata is supposed to contain information that is required for plugins to parse and serialize resources. In theory, we could make metadata generic.

But, given that lint is an "official" property of inlang provided by the @inlang/core/lint and pluggable via rules (need to agree on this :D ), I believe that we should add it to the AST nodes themselves.

[samuelstroschein]

@ivanhofer pluggable lint via rules is the right way to go, isn't it?

[ivanhofer]

yes, I would say so

[samuelstroschein]

Is validate a better name than lint?

Lint might be known among developers but what about non-technical users like translators?

[ivanhofer]

In the initial draft of pipeli18ne I have named the package checks.
I think validate is not correct since the package could also show you hints or warn you about some things that are not really a validation error. I would say the name lint is the standard in the JS ecosystem.

[ivanhofer]

Do translators interact with the package? Not really, so we can keep the name lint and in the editor we can show "Warnings" and "Errors"

[samuelstroschein]

Good argument. Just because we name the package does not neem we need to use the word lint among non-technical users.