feat(nfse): add the NBS and LC 116/2003 service list lookups - #569

Part of #541 (section 2, the two lookups). The access key family is in #565; this pull request branches from main and only meets #565 on alphabetical neighbours of src/index.ts, src/index.test.ts, the docs and the API report, but it is meant to merge after it.

Merge order: #565, then this pull request, then #566. #566 (claude/ibs-cbs) is stacked on this branch because it now imports the shared scripts/read-xlsx-sheet.ts added here; its base is claude/nfse-lookups until this merges.

What

Lookups for the two service classifications the national NFS-e carries: the NBS code (cNBS) and the subitem of the service list annexed to the Lei Complementar 116/2003 (the first four digits of cTribNac). Both datasets come with a generator under scripts/, wired into scripts/data.ts, so the Update datasets workflow refreshes them.

API

type Nbs = { code: string; description: string };
isValidNbs(value: string | number): boolean;
getNbs(value: string | number): Nbs | null;
formatNbs(value: string | number): string;

type ServiceItem = { code: string; description: string };
isValidServiceItem(value: string | number): boolean;
getServiceItem(value: string | number): ServiceItem | null;

getNbs("1.0101.11.00");
// { code: "101011100", description: "Serviços de construção de edificações residenciais de um e dois pavimentos" }
isValidNbs(101011100); // true
isValidNbs("1.0101"); // false (a position heading, not a complete code)
formatNbs("101011100"); // "1.0101.11.00"

getServiceItem("1.01"); // { code: "1.01", description: "Análise e desenvolvimento de sistemas." }
getServiceItem("0101"); // same subitem, from the first four digits of a cTribNac
isValidServiceItem("3.01"); // false (vetoed)
isValidServiceItem("99.01"); // false (national list only, not the law)

Both follow getCbo/getCfop: strict documented input forms, isLookupCode for numbers, own-property safe lookups (the key is always validated digits), null/false/"" on anything else. formatNbs has no pad option because every NBS code starts with 1. The NBS mask takes any single separator between the printed groups, like isValidCfop; a service subitem takes only the dot, because that is the only separator the law prints between the item and the subitem, the same way isValidCsosn rejects a grouping the official form never prints. Both the JSDoc and the docs pages say so.

Sources

• NBS: https://www.gov.br/mdic/pt-br/assuntos/sdic/comercio-e-servicos/nbs-nomenclatura-brasileira-de-servicos (MDIC). NBS 2.0, approved by the Portaria Conjunta RFB/SCS 1.429/2018 and amended by the Portaria Conjunta RFB/SCS 2.000/2018. The Anexo I PDF linked there states the code formation ("composto por nove dígitos": the digit 1, chapter, position, two subposition levels, item, subitem) and prints every code as N.NNNN.NN.NN. The dataset is generated from the official NBSa_2-0.csv linked on the same page (ISO-8859-1, header NBS 2.0;DESCRIÇÃO): 920 complete codes, the same count I get from the PDF, with the December 2018 renumbering applied (1.0402.11.10/.90, not .11/.19).
• TSCodNBS in tiposSimples_v1.01.xsd of the Sistema Nacional NFS-e is [0-9]{9}, which confirms the length the NFS-e expects.
• LC 116/2003: https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp116.htm. The numbering is item.subitem with a two digit subitem (1.01 ... 40.01); subitems 3.01, 7.14, 7.15, 13.01 and 17.07 are vetoed; 11.05 was added by the LC 183/2021.
• Dataset for the list: sheet LISTA.SERV.NAC. of ANEXO_B-NBS2-LISTA_SERVICO_NACIONAL-SNNFSe-v1.01-20260122.xlsx, https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual. The law has no machine readable form and the Planalto HTML mixes struck-through and amended text, so the generator reads this official workbook instead. I cross-checked it against the Planalto text with a throwaway script: the same 200 subitems in force, 195 descriptions identical character for character once whitespace is normalised and 5 differing only by punctuation or an accent (à/a in 15.07 and 15.08, nº/no in 1.09, the en dash of Cheques sem Fundos – CCF written as a hyphen in 15.05, and the final period dropped in 17.14). TSCodTribNac in the XSD documents the link: "2 para Item (LC 116/2003), 2 para Subitem (LC 116/2003) e 2 para Desdobro Nacional".

Generators

• scripts/nbs.ts: fetches the MDIC CSV, keeps the complete codes, fails below 900 codes or on a changed header. The fields are read the way RFC 4180 writes them: one row of the official CSV (1.1706.24.00) is a quoted field, and it used to ship with its quoting intact.
• scripts/service-items.ts: reads the link of the ANEXO B from the documentation page (the file name carries version and date, so nothing is pinned and a new version is picked up by the workflow), keeps the rows with DESDOBRO NACIONAL 0, SUBITEM above 0 and ITEM up to 40, fails below 190 subitems or on a changed header.
• scripts/read-xlsx-sheet.ts: a minimal .xlsx reader (zip central directory, node:zlib inflate, shared strings), so no development dependency is added for one workbook. readXlsxSheet reads one sheet by name; readXlsxSheets reads every sheet, by name, for a workbook whose sheet names change between versions (feat(ibs-cbs): add the CST-IBS/CBS and cClassTrib validators and lookups #566's cClassTrib table). It checks the signature of every central directory entry and of the local header it points at, inflates with a size cap per file and for the whole workbook and only the files it is asked for, drops the <rPh> phonetic readings of a shared string, decodes numeric character references, places a row by its r attribute rather than by document order, reads inline strings, resolves an absolute or upwards relationship target, and fails when the rows do not add up to the <dimension> the sheet declares. ZIP64 is not supported and the JSDoc says so.
• scripts/serialize-record.ts: writes a table out in key order. JSON.stringify follows insertion order and JavaScript hoists the keys that are canonical array indices, so the service list was emitted with 10.01 to 40.01 ahead of 1.01 to 9.03 although the record was built from sorted keys.
• Both generators were run twice and produce byte identical output. There is no scripts/data-summary.ts on main, so only scripts/data.ts was wired.

Shared with #566

#566 (claude/ibs-cbs) used to carry its own zip and xlsx reader inline in scripts/ibs-cbs.ts, and .jscpd.json covers scripts/ at threshold 0, so both could not land as they were. scripts/read-xlsx-sheet.ts is now the one reader: it took over what #566's copy did that this one did not (the whole-workbook inflate cap, the phonetic runs, reading every sheet) on top of the central directory signature check, the per-file cap and the numeric entity decoding it already had, and decodeXml moved into scripts/decode-xml.ts so #566 can decode its portal listing with it. #566 is rebased on this branch and imports the reader. Both sheets of the ANEXO B workbook and both sheets of the cClassTrib workbook come out of the reworked reader cell for cell as before, and npm run check:duplication reports 0 clones with both pull requests applied.

Bundle size

From npm run build && npm run check:tree-shaking; both getting-started tables were updated:

The issue asked whether the full NBS should ship: with the headings left out it is smaller than the CNAE and CBO tables already in the package, so it ships whole, descriptions included.

Verification

• npm run check: pass.
• npm run test -- --run: 6260 passed.
• npm run test:coverage: 100% statements, branches, functions and lines.
• npm run build (attw and publint clean), npm run check:api:update (report committed), npm run check:unused, npm run check:duplication (0 clones), npm run check:tree-shaking, npm run check:commits: pass.
• npm run test:mutation -- --mutate on the five new files: 100% (40 mutants, none surviving, no Stryker disable comments).
• npm run test:bun and npm run test:deno: pass.
• npm run build:llms and npm run build:site were run.
• Both generators were re-run against the live official files after the fixes: the NBS table changes in exactly the one description that was quoted, and the service list comes back with the same 200 entries and the same wording, only written out in key order.
• Not run, per the shared-machine instructions: browser test scripts, the full Stryker run, and npm run build:data as a whole (only the two new generators were run, so the other datasets are untouched).

Open points

• The ANEXO B of the NFS-e lists the NBS 2.0 minus three codes (1.0402.29.00, 1.0403.29.00, 1.0904.40.00) and adds a placeholder 9.9999.99.99. isValidNbs follows the nomenclature itself (MDIC), so those three are valid here although the NFS-e would refuse them; the docs say so. An options switch for "the subset the NFS-e accepts" could be added later without breaking anything.
• The 49 descriptions where the ANEXO B wording differs from the MDIC CSV (mostly an added comma) follow the MDIC CSV.
• Subitem 17.14 is "Advocacia" without the final period every other description of the table ends with. The official sheet is what drops it and the law prints 17.14 – Advocacia.; the table follows the sheet rather than normalising it, so the dataset stays exactly what the official file says. A test pins it.
• cTribNac, the 6 digit national tax code (item + subitem + national split, 338 codes), is in the same sheet and would be a natural isValidCTribNac/getCTribNac later; it was not in the issue's API, so it is left out. Item 99 of the national list is not part of the law and is rejected by isValidServiceItem.
• Municipal service codes (cTribMun) vary by municipality and are out of scope, as are the item headings (1, 2, ...) and the NBS headings.
• The section heading "Classification codes (CBO, CNAE, NCM, CFOP, CST, CSOSN)" in the docs was left as it is to keep its anchor stable and the diff small against sibling pull requests.
• The branch was rebased once to drop the Signed-off-by trailer from the first commit, since the recent history of main carries none. Nothing else in the commits changed and the tree is identical.

Summary by CodeRabbit

• New Features

  • Added NBS 2.0 utilities for formatting, validating, and looking up Brazilian service classification codes with official descriptions.
  • Added utilities for validating and looking up current LC 116/2003 service items, including normalized codes and descriptions.
  • Supports formatted, unformatted, numeric, whitespace-separated, and zero-padded inputs where applicable.

• Documentation

  • Added usage guidance, API references, dataset details, bundle-size information, and examples in English and Portuguese.
  • Updated architecture documentation to include the NBS and LC 116/2003 datasets.