Filter dependencies by file

[timothymcmackin]

Eventually we'll want to filter the dependency check by file, so this PR reworks the script into accepting three params:

• You can check specific tools by passing them to the script, as in npm run check-dependencies -- --dependencies=smartpy,taquito.
• By default, the script checks for differences down to the fixpack level, but you can pass --major or --minor to check for differences at those levels.
• By default, it checks all files, but you can pass individual files to check in a comma-separated list, as in npm run check-dependencies -- --filesToCheck=docs/developing/octez-client/accounts.md,docs/tutorials/build-your-first-app.md.

The script has error-checking to catch unknown parameters and dependencies. If you pass an incorrect file path, you'll get the usual Node ENOENT error for the missing file.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs-staging	✅ Ready (Inspect)	Visit Preview	Jan 30, 2025 2:39pm

[NicNomadic]

Nice idea to enable restricting to a set of files! But specifying the files as an option is not as flexible as providing them as command arguments, letting the shell expand wildcards and all. For instance:

• npm run check-dependencies -- --filesToCheck="docs/developing/octez-client/*.md" complains about a non-existent file, while it should find several ones (also tried without the quotes)
• instead, npm run check-dependencies -- --filesToCheck=docs/developing/octez-client/*.md could check all the matching files

[NicNomadic]

(My remarks are just comments, I'm not against keeping the UI as it is, if you prefer it; I just wanted to see if a review requesting changes creates a thread or no -- but visibly not!)

[timothymcmackin]

But specifying the files as an option is not as flexible as providing them as command arguments, letting the shell expand wildcards and all.

We could adapt to accept wildcards, but this script is mainly for the CI, and a github action will list all changed files in a PR without wildcards.

[NicNomadic]

But specifying the files as an option is not as flexible as providing them as command arguments, letting the shell expand wildcards and all.

We could adapt to accept wildcards, but this script is mainly for the CI, and a github action will list all changed files in a PR without wildcards.

Well, I imagine that the github action will not use the --filesToCheck argument either, will it? So I think the whole point for adding this argument is to complement the automatic use by possible manual uses, in which this flexibility may help. Or what is the use case you think of?

[timothymcmackin]

But specifying the files as an option is not as flexible as providing them as command arguments, letting the shell expand wildcards and all.

We could adapt to accept wildcards, but this script is mainly for the CI, and a github action will list all changed files in a PR without wildcards.

Well, I imagine that the github action will not use the --filesToCheck argument either, will it? So I think the whole point for adding this argument is to complement the automatic use by possible manual uses, in which this flexibility may help. Or what is the use case you think of?

We can feed the list of files from the github action to any place in the command, as in this example:
https://github.com/trilitech/tezos-developer-docs/blob/main/.github/workflows/tests.yml#L31

I don't have a strong opinion about this; if we think people are going to test files manually on the CLI I can make this an anonymous CLI option

[NicNomadic]

We can feed the list of files from the github action to any place in the command, as in this example: https://github.com/trilitech/tezos-developer-docs/blob/main/.github/workflows/tests.yml#L31

I don't have a strong opinion about this; if we think people are going to test files manually on the CLI I can make this an anonymous CLI option

Being able to run this checks manually in a flexible way will definitely be useful for us, maintainers, for planning the work at different levels of priorities. Say we don't have time to retest all the tutorials reported by the github actions, but we want to retest just those:

• depending on an old protocol
• depending on a major change of Smartpy (while usually we also consider minor changes)
• or depending on a minor change of Octez (this would be unusual, too, but could be justified in case of a critical bugfix)
• etc.

As we cannot anticipate all the possible scenarios, being able to execute different queries will allow us to adjust the changes to the resources we have.

So yes, for this reason, it would be nice to accept shell-expanded arguments as lists, passed as an anonymous option.

[timothymcmackin]

So yes, for this reason, it would be nice to accept shell-expanded arguments as lists, passed as an anonymous option.

Having a named parameter doesn't prevent any of this, but if you prefer it that way, fine, I made the file names an anonymous parameter, as in this example:

npm run check-dependencies -- --major -d=smartpy,taquito docs/developing/octez-client/accounts.md docs/tutorials/build-your-first-app.md

[NicNomadic]

Thanks, I think it's much more flexible now, that I can do a command like this:

npm run check-dependencies -- --major -d octez docs/tutorials/*.md

So the UI is perfect now!

[NicNomadic]

As a minor issue, I experienced a failure when omitting the --, but it's not a blocker:

npm run check-dependencies --major -d octez docs/tutorials/*.md

[timothymcmackin]

As a minor issue, I experienced a failure when omitting the --, but it's not a blocker:

npm run check-dependencies --major -d octez docs/tutorials/*.md

The -- is necessary so the arguments go to the check-dependencies script and not to the npm command, so it's unavoidable.

[NicNomadic]

The -- is necessary so the arguments go to the check-dependencies script and not to the npm command, so it's unavoidable.

Fine then, LGTM.